Commit eb5973f6 authored by 谢宇轩's avatar 谢宇轩

docs: sync README with First-Run Setup, --help, and new archive flow

- Point config setup + Agent 自主配置 to SKILL.md's First-Run Setup
  (was duplicating onboarding steps that now live in SKILL.md)
- Add --help mention for both scripts
- Update 归档产物结构 with sentinel intermediate state + temp files
  (.manifest.json / .summaries.json)
- Update budget reference: full body no longer in context → lower cost
  (~$1.0 archive, ~$0.3 preview); max-budget $5 → $3
parent bd73bb2c
......@@ -106,7 +106,7 @@ ln -s "$(pwd)" ~/.claude/skills/news-harvester
### 3. 生成配置
首次运行任意脚本会自动从 `references/config-template.json` 复制生成 `config.json`。但**在首次采集前**,必须编辑 `config.json` 设置你的 vault 路径:
首次运行任意脚本会自动从 `references/config-template.json` 复制生成 `config.json`。但**在首次采集前**,必须`vaultPath` 从模板占位符 `/path/to/your/obsidian/vault` 改为你的真实 Obsidian vault 路径:
```jsonc
{
......@@ -116,7 +116,7 @@ ln -s "$(pwd)" ~/.claude/skills/news-harvester
}
```
也可以让 Agent 在运行时自动配置(见下方「Agent 自主配置」)。
手动编辑或让 Agent 自动配置均可——Agent 加载本 skill 时会主动检测占位符并引导配置(详见 `SKILL.md`**First-Run Setup** 小节)。
---
......@@ -124,7 +124,12 @@ ln -s "$(pwd)" ~/.claude/skills/news-harvester
### 交互模式 / 无头模式
所有任务都可以通过自然语言驱动,Agent 会加载本 skill 并调用脚本:
所有任务都可以通过自然语言驱动,Agent 会加载本 skill 并调用脚本。每个脚本都支持 `--help` 查看用法:
```bash
node scripts/harvest.js --help # 采集/预览的用法、模式、示例
node scripts/finalize.js --help # 补全摘要的用法、前置条件、示例
```
#### 任务 1:添加数据源
......@@ -179,23 +184,17 @@ claude -p \
--output-format json \
--permission-mode bypassPermissions \
--allowed-tools "Bash" "Write" \
--max-budget-usd 5 \
--max-budget-usd 3 \
"使用 news-harvester skill,采集 the-conversation 最新 3 篇文章并归档到 Obsidian"
```
> 💡 预算参考(实测):添加数据源 ~$0.8|返回 JSON ~$1.0|完整归档 ~$2.2。多步骤任务建议 `--max-budget-usd` 设为 $3–5
> 💡 预算参考(重构后实测):预览数据 ~$0.3|完整归档(harvest → 摘要 → finalize)~$1.0。全文不再进入 Agent 上下文,token 消耗大幅下降。多步骤任务建议 `--max-budget-usd` 设为 $2–3
---
## Agent 自主配置
当其他 Agent 首次加载本 skill 时,`config.json` 可能不存在或含模板占位符。Agent 应按以下流程自主配置:
1. **检测**:运行 `node scripts/source-manage.js list`。若报错或 `vaultPath` 仍为 `/path/to/your/obsidian/vault`,说明未配置。
2. **设置 vaultPath**:询问用户或从环境推断 Obsidian vault 路径,写入 `config.json`
3. **添加数据源**(可选):用 `source-manage.js add` 或直接编辑 `config.json`
4. **验证**:确保 `vaultPath` 目录存在且可写(`mkdir -p <path>`)。
5. **运行采集**`node scripts/harvest.js <source_id> <count>`
当其他 Agent 首次加载本 skill 时,`config.json` 可能不存在或仍含模板占位符 `/path/to/your/obsidian/vault`。Agent 会主动检测这一状态并在采集前引导完成首次配置——详见 `SKILL.md`**First-Run Setup** 小节(检测占位符 → 设置 vaultPath → 确认数据源 → `--preview` 冒烟测试)。
配置字段说明见 `SKILL.md`**Configuration** 小节。
......@@ -221,14 +220,18 @@ claude -p \
```
YYYYMMDD/
├── <中文标题>.md # 中文摘要(事件概述/背景/关键引语/影响分析)
├── <英文标题> - <SourceName>原文.md # 英文原文(含配图)
├── <中文标题>.md # 中文摘要(事件概述/背景/关键引语/影响分析)— finalize.js 生成
├── <英文标题> - <SourceName>原文.md # 英文原文(含配图)— harvest.js 生成,finalize.js 修补中文标题链接
├── index.md # 当日索引(分类统计 + 文章列表 + 分类导航)
├── registry.json # 去重注册表
└── assets/
└── <slug>-N.jpg # 下载的配图
├── assets/
│ └── <slug>-N.jpg # 下载的配图
├── .manifest.json # ⏳ 临时:harvest.js 写,finalize.js 消费后删除
└── .summaries.json # ⏳ 临时:Agent 写,finalize.js 消费后删除
```
> harvest → finalize 之间,原文/registry/index 里的中文标题是哨兵占位符 `__SUMMARY_<slug>__`,finalize 完成后替换为真实标题。两个 `.` 开头的临时文件在 finalize 后自动删除。
中英文档通过 YAML frontmatter 的 `related` 字段双向 `[[链接]]`
---
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment