常见问题

本页目录

按遇到的先后排：电脑基础 → 装 Skill → 用 Skill → 取数与环境 → 沉淀与测试 → 导出与历史图 → 提交口径。

一、电脑基础

1. Tab 是哪个键？Ctrl、Esc 在哪？

Tab：键盘左侧、字母 Q 左边，上面印着 Tab 或 ⇥。在终端里输入文件名的前几个字再按 Tab，会自动补全；Claude Code 里输入 /ht 再按 Tab，会补成 /html-slides。
Ctrl：键盘左下角。Mac 上写作 control，和 command（⌘）是两个键。本手册里的 Ctrl + C 在 Mac 上也是按 control + C。
Esc：键盘左上角。Claude Code 干活时按一下让它停下。
Enter：回车键，Mac 上写作 return。

2. “建项目”是什么意思？

建一个文件夹，把这件事要用的文件都放进去，再用 VS Code“文件 → 打开文件夹”打开它，在它的终端里运行 claude。在哪个文件夹启动 claude，它就把哪个文件夹当成项目：读哪份 CLAUDE.md、找哪个 .claude/skills/、Git 版本记录建在哪里，都看这个文件夹。

检查方法：Claude Code 欢迎界面第三行显示的路径，应当是你的项目文件夹。不是的，按两次 Ctrl + C 退出，用 VS Code 重新打开对的文件夹再启动。

3. 电脑上没有 VS Code

先按 W01 安装手册装：https://ai.lingnan.top/materials/2026-autumn/w01/installation。装好之前：

启动 Claude Code：Mac 打开“终端”，Windows 打开 PowerShell；先输入 cd （后面有空格），把项目文件夹从访达或资源管理器拖进终端窗口，路径会自动填上，回车；再输入 claude。
看文件、拖文件：用访达或资源管理器，先让隐藏文件夹显示出来（见第 6 条）。

4. 下载的文件在哪？

浏览器默认下载到“下载”文件夹：Mac 是 /Users/你的用户名/Downloads，Windows 是 C:\Users\你的用户名\Downloads。找不到时点浏览器右上角的下载图标，再点“在文件夹中显示”。

5. 路径里的 `/`、`\`、`~` 是什么？

路径是文件夹一层层的地址。Mac 用 / 分隔（/Users/你的用户名/Documents/网页演示练习），Windows 用 \ 分隔（C:\Users\你的用户名\Documents\网页演示练习）。~ 是你的用户文件夹的简写。对 Claude Code 说话时，写项目内的相对路径就行，例如 素材/、.claude/skills/。

6. 找不到 `.claude` 文件夹

名字以点开头的文件夹默认隐藏，不是没有。

Mac 访达：Command + Shift + .（句点），再按一次恢复隐藏。
Windows 11 资源管理器：“查看 → 显示 → 隐藏的项目”；Windows 10：“查看”选项卡里勾选“隐藏的项目”。
VS Code 文件栏默认就显示，在那里操作最方便。
Mac 访达不让直接新建以点开头的文件夹：在 VS Code 文件栏里新建，或让 Claude Code 建。

7. 看不到 `.txt`、`.md` 这些后缀，改名改不对

Windows 资源管理器：“查看 → 显示 → 文件扩展名”。Mac：访达“设置 → 高级 → 显示所有文件扩展名”。在 VS Code 文件栏里右键“重命名”，能看到完整文件名。把 gitignore_白名单.txt 改成 .gitignore 时，.txt 要一起删掉。

二、下载与安装 Skill

8. GitHub 打不开，或者下载很慢

换一个网络（手机热点、校园网切换）再试；刷新几次。还不行，找助教或同学用 U 盘拷一份解压好的 sysu-awesome-cc-main 文件夹。

9. Windows 上双击 ZIP，拖出来的文件夹不全

双击 ZIP 看到的是预览，不是解压。右键 ZIP →“全部解压缩…”→“提取”，再从解压出来的文件夹里拷。Windows 解压出来外面会多一层同名文件夹：sysu-awesome-cc-main\sysu-awesome-cc-main\skills\…，进到里面那层再找 skills。

10. `/skills` 里看不到 `html-slides`

逐条查：

路径：必须是 项目文件夹/.claude/skills/html-slides/SKILL.md。常见放错：多了一层（.claude/skills/sysu-awesome-cc-main/…）、少了一层（.claude/skills/SKILL.md，外面没有 html-slides 文件夹）、.claude 放到了项目外面、文件夹名拼成了 .claude/skill（少个 s）。
没有重开：.claude/skills/ 是 Claude Code 启动后才建的，要退出再启动一次。
启动位置不对：看欢迎界面第三行的路径是不是项目文件夹（第 2 条）。
文件格式：SKILL.md 第一行必须是 ---，前面不能有空行；name: 与文件夹同名。直接从仓库拷来的不会有这个问题，自己改过的才会。

都对还是不行：直接问它“你有哪些技能可用”，或者用 /html-slides 点名试一次。

11. 按两次 Ctrl + C 之后怎么办？重开是不是新对话？

按第一次：屏幕下方出现 Press Ctrl-C again to exit；紧接着按第二次：Claude Code 退出，回到命令行提示符。这只是退出，要再输入 claude 回车才是重新打开。
重新打开就是一个新会话：屏幕上没有上一次的对话，它重新读取项目规则和技能清单。旧对话没丢，存在你电脑上。
想接着上次聊：启动时输入 claude --continue（接最近一次）或 claude --resume（从列表里选）。
/clear 是不退出、清空对话；第一次建技能文件夹后，统一用退出重开。

12. 用 Codex，技能放哪？

项目级放项目文件夹里的 .agents/skills/，个人级放 ~/.agents/skills/。早期文档写的是 .codex/skills，目前仍能读取，但官方文档已改为 .agents/skills。Codex 里点名技能用 $技能名，例如 $html-slides。

13. 我用的是 VS Code 里的 Claude 图形面板，不是终端

图形面板也能用 Skill，但有些命令只在终端里的命令行界面有。输入 /export、/skills 等看到 isn't available in this environment 的，打开 VS Code 终端（“终端 → 新建终端”）输入 claude，在那里做。图形面板里重开会话：关掉面板再打开，点“新对话”。

三、用 Skill

14. 它要装 Playwright、要生成配图、要导出 PDF

html-slides 正文里有配图、截图审阅、导出 PDF 这几步，要另装程序。本练习不需要：拒绝它的安装请求，再说一遍“不要配图，不做截图审阅，不导出 PDF，只做 HTML”。

15. 自然说话时屏幕上没出现 `Skill(html-slides)`

它没想起这个技能，可能是你的话和描述对不上。两个办法：把话说得更像描述里写的（“做一份网页演示文稿”“做幻灯片”）；或者直接点名 /html-slides 你的要求。已经做出来但没用技能的，用点名重做一次。

16. 双击 `index.html` 没反应，或者打开是一堆代码

打开是代码，说明是用文本编辑器打开的。右键 →“打开方式”→ 选 Chrome、Edge 或 Safari。VS Code 里点开 HTML 看到的也是代码，要到访达或资源管理器里双击。

17. 改完了，浏览器里还是旧的

按 F5（Mac Command + R）刷新。还是旧的，确认打开的是它改的那个 index.html（有时它会新建一个文件夹）。

四、取数与环境（练习二）

18. 第一次用 `macro-data`，它说要装 Python 或 AKShare

正常。第一次用时它会先检查你电脑上的环境，缺什么说什么：要装什么、装到哪里、大约多久。按提示确认后再装，每条命令都会请你批准；要你自己动手的地方（双击安装包、勾选某个选项），它会一步一步说。没说清楚的先问它，不懂就不批准。

19. 输入 `python`，弹出了微软应用商店

那是 Windows 自带的占位程序，不是装好了。让它按 macro-data 的说明处理：通常改用 py 命令，或者从 python.org 装官方安装包（选 64 位的 “Windows installer (64-bit)”）。装完 Python 要把终端、VS Code 和 Claude Code 都关掉再重新打开（在 VS Code 终端里用 Claude Code 的，要关掉整个 VS Code，只关终端面板不够），新装的程序才找得到。

20. 装包很慢或报错

把报错原文发给它，让它按 macro-data 里的排查表处理（换镜像、加 --user、关掉代理等）。Windows 上报 Microsoft Visual C++ 14.0 is required，或者 mini-racer 装不上，多半是装了 32 位 Python：让它先运行 macro-data 的环境检查，看“Python 位数”一行，是 32 位就卸掉，重装 “Windows installer (64-bit)”。装了很久还跑不通，不要一直耗着，改用材料包里的备用数据（手册练习二“取不到数怎么办”），在 取数记录.md 写清卡在哪一步、报的什么错。

21. 它要装 Miniconda 或建 conda 环境

macro-data 的写法是：电脑上已有 conda 的用 conda，没有的用系统 Python 加 pip，不必为此装 conda。它要你新装 Miniconda 的，告诉它“我没有 conda，不装 conda，用系统 Python”。

22. 取到的数据，最新一期是一年前的

有的接口会滞后很久，macro-data 的 SKILL.md 里写了这类坑。让它换一个接口重取，并在 取数记录.md 的“是否滞后”一栏写明。

23. 取数时报代理错误、超时

国家统计局和 AKShare 都是国内网站。开着全局代理（翻墙软件）的，关掉再试；还不行把报错发给它。

24. 两个来源的数对不上

先看口径：当月同比还是累计同比、初值还是修订值、官方 PMI 还是财新 PMI。以原发布（国家统计局、中国人民银行官网）为准，在“数据与口径”页写明用的哪个，在“局限”页写明差异。

25. 取不到的指标能不能自己估一个？

不能。写“未取到”，在“局限”页说明。用备用 CSV 补的，逐个标来源。

25a. 取数记录是什么，一行怎么填？

宏观数据/ 里的 CSV 保存数据，每个指标一份 CSV，每行数据带获取时间、来源机构、原始来源链接、发布标题、发布日期，经二手接口取的另写接口名。协作记录/取数记录.md 是这些数据的汇总说明，每个指标汇总一行，不是把 CSV 的每一行再抄一遍，也不能代替 CSV 里的逐行来源列。

下面按 取数记录_模板.md 的栏目示范一行。指标、机构、文件、日期和链接均为虚构占位，不是真实取数结果，不能当作自己的记录使用。

指标	类别	接口或文件	获取时间	来源机构	最新一期原发布链接	最新一期发布标题与日期	覆盖期间	最新一期	是否滞后	数据文件	来源列是否齐全	备注
示范景气指数（虚构）	景气	示例接口名	20XX-09-10 10:30	示例发布机构	`https://example.invalid/release`	《示范指数发布》；20XX-09-09	20XX-01 至 20XX-08	20XX-08	待核验	`宏观数据/示范景气指数.csv`	待核验	格式示范，不含真实数据

实际填写时，从这次保存的数据文件、取数过程和原发布中逐项核对；“是否滞后”要把接口最新一期与原发布最新一期对照后再写，不能因为取数成功就填“否”。链接没找到写“未找到”，数据没取到写“未取到”，不凭空补齐。

给 AI 的取数指令可以换成自己的说法，但要保留四件事：每个指标一份 CSV；每行带来源信息；核对每个指标的最新一期；按模板汇总接口或文件、获取时间、来源机构、最新一期的原发布链接与标题日期、覆盖期间、最新一期和是否滞后等字段。不确定是否漏项，就回手册练习二第 3 步对照完整指令。

五、沉淀与测试（练习三）

26. `skill-creator` 开始跑评测，停不下来

按 Esc，再说一遍“不要跑评测，先给我看草稿”。

27. 用 Codex，新技能跑到了 `~/.codex/skills`

沉淀指令里没写位置。Codex 自带的 skill-creator 默认写到个人级旧路径。让它把整个文件夹移到项目的 .agents/skills/macro-fundamentals-report/，以后指令里写明位置。

28. 新技能里写死了“某年某月 CPI 多少”

让它改成做法，例如“先确认每个指标最新一期是哪个月”“每条数据记下获取时间、来源机构、原发布链接和发布日期”。技能是下次用的，这次的数下次就过时了。

29. 测试时它没用新技能，直接照抄了项目里已有的演示文稿

项目里已经有一份成品时，它可能照着旧文件改。先按第 30a 条确认新 Skill 能按预期自然触发，再换一个时间窗口或指标组合，输出到新文件夹，核对实际调用记录和取数过程，看它是不是从取数做起。做完可以问它“你按哪个技能的第几步做的”，但要对照记录核实，不能凭这句回答认定通过。

30. 该来的没来 / 不该来的来了

先按第 30a 条确认新 Skill 已加载，再看触发结果是否符合预期，不把未调用直接归因于 description。

该来没来：检查 description 是否写清任务，以及你平时表达这个任务的说法；缺了就补上，在同项目的新会话里重测。
不该来却来了：检查描述的适用范围是否过宽；补一句“不用于只查一个数、不写投资建议”一类的边界，在新会话里重测。

30a. 新 Skill 没被调用，按什么顺序排查？

先检查加载和触发，再做完整任务，不用反复生成整份演示文稿来试。

同项目、新会话，先看 /skills。 留在练习二的 宏观基本面汇报/ 项目里，退出后重新运行 claude，输入 /skills，找 macro-fundamentals-report。列表里有它，说明当前会话已识别这个 Skill，不表示已经执行了正文。新会话不等于新文件夹。
列表没有，先查位置和文件。 核对启动位置是不是原项目、路径是不是 .claude/skills/macro-fundamentals-report/SKILL.md，再检查文件名、开头的 ---、name 和 description 是否写好；改后在同项目里退出重开，再看列表。用 Codex 的项目路径是 .agents/skills/，点名用 $技能名；这里的 /skills 与界面示例按终端版 Claude Code 写，面板提示不可用时见第 13 条。
列表有了，再用自然说法测触发。 不先要求它读 SKILL.md，也不点名 /macro-fundamentals-report；直接用手册练习三 C 的三句话分别测试，每句在一个新会话里说。观察是否出现 Skill(macro-fundamentals-report) 这样的实际调用记录，不能用它口头说“我用了”代替。看清触发结果后可按 Esc 停下，不必每句都生成成品。
不符合预期，先排查、重测。 有技能却没按预期调用，回第 30 条核对描述与任务边界；也可以在另一个会话里手动点名，区分“点名能不能用”和“自然说话会不会调用”。改过后重新开会话，用原来的自然说法重测；仍不符就保留测试句、列表与调用记录、报错原文，继续定位，不凭未核验的配置猜原因。
触发测试通过后，再完整运行。 两句应调用的调用了、一句不应调用的没调用，再换时间窗口或指标组合，把产物写到同项目的 汇报_测试/。核对它是否按新 Skill 从取数做起，以及数据来源、自检和演示文稿是否符合要求；不要把旧文件改个名字当成跑通。

四件事分开判断：

看到什么	能说明什么	还不能说明什么
你或 AI 读了 `SKILL.md`	看到了文件内容	已被技能系统识别或自然触发
手动点名 `/macro-fundamentals-report` 后调用成功	点名能调用	自然说话也会调用
未点名的自然说法出现新 Skill 的实际调用记录	这句触发了新 Skill	整个任务已按要求做完
生成了 HTML，打开后有内容	文件生成了	用了新 Skill，或触发、取数、自检都通过了

31. 提交时把下载来的技能也提交了

用材料包里的白名单 .gitignore，它会让 html-slides、macro-data、skill-creator 三个下载来的文件夹不进版本记录，你自己造的技能照常记录。已经提交进去的，让它“把这三个文件夹从版本记录里移除，但保留文件”，它会用 git rm --cached，文件还在，先让它报告再放行。

六、导出对话与历史图

32. `/export` 不可用

看到 /export isn't available in this environment.：你是在非终端环境里输入的（VS Code 图形面板等）。打开 VS Code 终端，输入 claude，在终端里的 Claude Code 里输入 /export。要导出的是之前那次会话的，先 claude --resume 选中它，再 /export。
在终端里输入 /export 弹出了菜单：用方向键选“保存为文件”，回车；或者直接带文件名：/export 协作记录/对话记录_练习二.txt。
用 Codex 的：Codex 的会话记录按日期存在 ~/.codex/sessions/ 下；让 Codex 帮你找到这次会话的记录文件，拷一份进 协作记录/。

33. 会话被压缩后导出不全

会话很长时，Claude Code 会自动压缩（屏幕上出现 Conversation compacted），把前面的对话换成摘要；你输入 /compact 也会压缩。压缩之后 /export，导出的是摘要加压缩之后的内容，压缩前的原话不在里面。

做到一半被压缩的：先 /export 导出当前这份记录；压缩之前导出过的那份也要交，压缩前后的记录都交。不要让 AI 回忆着把压缩前的内容补写出来。

压缩前的完整记录还在你电脑上，导出的不全时可以找回：

屏幕上按 Ctrl + O 可以翻看完整历史。
完整记录存在 Claude Code 的会话文件里：用户文件夹下 .claude/projects/ 里，以项目路径命名的那个文件夹中，扩展名是 .jsonl，一次会话一个文件。可以对 Claude Code 说：“找到这次会话在 ~/.claude/projects/ 下的 jsonl 记录文件，复制一份到 协作记录/。”这个文件是给程序读的格式，内容完整但不好读。

以后做长任务：每个练习做完就 /export 一次，别等到最后。

34. 导出的文件放进项目后，Git 说有未提交的改动

白名单 .gitignore 只放行 .md、.html、.csv、.py 和技能文件夹，导出的 .txt 不会进版本记录，Git 不会提示。你用的不是白名单的，导出到 协作记录/ 以外的地方，或者让它把这个文件加进 .gitignore。

35. Git Graph 打不开

先分清两样东西：

源代码管理图：VS Code 自带。左侧点“源代码管理”图标（或 Ctrl + Shift + G，Mac 同样），面板下方有“源代码管理图”，折叠着的点标题展开。
Git Graph：一个扩展，要先在 VS Code 扩展商店搜“Git Graph”安装。装好后，源代码管理面板顶部有它的图标；或者 Ctrl + Shift + P（Mac Command + Shift + P），输入 Git Graph: View Git Graph。

打不开、是空的，多半是下面几种：

VS Code 打开的不是项目文件夹（打开了上一级，或者只打开了一个文件）。用“文件 → 打开文件夹”重新打开项目文件夹。
项目还没开启版本记录（没有 .git 文件夹）。让 Claude Code 先 git init 并提交一次。
Git Graph 没装。用自带的源代码管理图也可以。

36. `git log --oneline` 在哪里运行？

在终端里运行，不是在 Claude Code 的输入框里。VS Code 里再开一个终端（终端面板右上角的 +），或者先按两次 Ctrl + C 退出 Claude Code。也可以直接问 Claude Code：“运行 git log --oneline 给我看”。

七、提交口径（李老师 2026-10-06 确认）

37. 练习二、练习三连续做，只导出了一份完整的交互记录，两个练习都能交吗？

可以。同一份完整的交互记录，可以同时放进练习二和练习三的交互记录框，不用拆分。

38. 练习二修改之前的版本没有存档，是用历史脚本重建的，能交吗？

可以交。重建的文件要标明是重建稿：在文件里或 协作记录/取数记录.md 里写明“由历史脚本重建，非原始存档”。是否影响评价由老师逐份看，不作承诺。

39. 演示文稿超过 8–10 页，可以吗？

可以。页数是建议范围，不是硬性上限，练习二、练习三都一样。建议 8–10 页左右，是为了在做到交互要求、用上最佳实践的前提下，不让同学额外多花 tokens。已经做完、页数超出的，不要求删减或重做；不拼页数，页数多也不加分。练习三没有页数上限。