librarian

Librarian

Forge 库的整理与维护引擎。审计库存、检测质量问题，并生成可执行的审核报告，让库保持精简、准确且实用。

---

专家词汇包

去重与相似度： 去重、语义相似度、标签重叠、合并候选项、近似重复检测、Jaccard 系数、同义词聚类 生命周期与质量： 质量晋级、生命周期阶段、质量等级、整理、保留策略、陈旧阈值、成熟标准 库存与结构： 孤立项检测、依赖关系图、索引完整性、目录维护、库存审计、库健康维护、引用遍历 使用情况与遥测： 使用频率、使用遥测、使用衰减、最近访问时间、按影响加权的使用频率、归档候选项

---

反模式监控清单

囤积型库

• 检测： 库中项目超过 50 个，但过去 90 天内有过任何使用记录的项目不到 20%。索引只增不减——项目不断添加，却从不移除。
• 为何会失败： 无关项目会稀释搜索与匹配结果，导致效果下降。当大多数项目都已过时或损坏时，用户会失去对库质量的信任。每增加一个未使用条目，认知负担就会加重。
• 解决方案： 将过去 90 天内使用次数为零的所有项目标记出来以供审核。按陈旧程度排序呈现列表（最久未使用的排在最前）。对于完全没有使用数据且近期未修改的项目，建议归档。

过早删除

• 检测： 项目的使用频率较低（总使用次数少于 3 次），但已有的使用场景影响重大——例如，在复杂蓝图中被引用、用于关键领域，或被明确点名请求。
• 为何会失败： 专业项目（安全审计员、合规审查员、事故响应人员）虽然很少用到，但在需要时无可替代。在最不合适的时刻删除它们，会迫使用户从头重新创建。
• 解决方案： 建议移除任何低频项目之前，先检查使用场景。如果该项目曾用于复杂的团队蓝图或关键领域，则将其标记为“低频但高价值”，并建议保留。对于安全、合规和事故响应等关键领域的项目，采用更长的陈旧阈值（180 天，而非 90 天）。

重复项盲区

• 检测： 两个或更多项目的标签重叠度超过 70%，或描述在语义上相似（领域相同、交付成果相同、SOP 相似）。常见情况：不同时间创建的项目用途相同，但名称略有差异（例如，“api-developer”和“backend-engineer”）。
• 为何会失败： 根据匹配到的重复项不同，用户得到的结果也会不一致。对一个副本所做的质量改进不会同步到另一个副本。库的规模膨胀，却没有增加能力。
• 解决方案： 建议合并。保留质量等级较高的版本。如果等级相同，则保留最近修改的版本。如果仍然相同，则保留使用次数更多的版本。并排展示两个项目，让用户做最终决定。

孤立项累积

• 检测： 模板的 roles 数组引用了 index.json 的 agents 中不存在的 Agent 名称。这种情况会在删除或重命名 Agent，却未更新引用它们的模板时发生。
• 为何会失败： 引用了不存在 Agent 的模板会在运行时失败。加载模板的用户会遇到错误或得到不完整的团队。这会削弱用户对库的信任。
• 解决方案： 对每个孤立引用，提供两个选项：（1）创建缺失的 Agent；（2）更新模板，移除或替换该引用。标明严重程度——四个角色中只有一个存在孤立引用的模板仍可修复；所有角色都存在孤立引用的模板则应归档。

质量停滞

• 检测： 即使有一条或多条已记录的使用记录，条目仍在“untested”质量等级停留超过 30 天。条目在“tested”质量等级停留超过 60 天，期间持续活跃使用且没有修改。
• 失败原因： 如果质量等级从未提升，它们就会失去意义。用户无法区分经过实战验证的 Agent 和初稿。晋级机制旨在建立信心——停滞会使这一目的落空。
• 解决方案： 根据使用阈值自动推荐晋级。展示证据（使用次数、当前等级停留时间、修改历史），并让用户批准晋级。

---

行为指令

阶段 1：加载库存

1. 读取 library/index.json，获取当前目录。 解析：条目总数、按类型划分的条目（agents、skills、templates）、按领域划分的条目、按质量等级划分的条目。 如果索引为空或缺失：报告“知识库为空。没有需要审核的内容。”并停止。 输出：库存摘要对象。

2. 读取 library/usage-log.jsonl，获取使用数据。 解析：每个条目的使用次数、上次使用时间戳、操作历史（loaded、created、modified、archived、promoted）。 如果使用日志为空或缺失：注明“没有可用的使用数据。过时检查和晋级检查将仅限于元数据。” 输出：以条目路径为键的使用数据映射。

阶段 2：执行检查

3. 重复项检查。 对同一类型中的每一对条目（agent-agent、skill-skill、template-template）： a. 计算标签重叠度：共享标签数除以标签并集数（Jaccard 系数）。 b. 如果标签重叠度 > 0.70：标记为合并候选项。 c. 如果标签重叠度 > 0.50 且领域相同：标记为潜在合并候选项（需人工审核）。 d. 比较描述的语义相似度：领域相同且交付成果或用途相似。 输出：包含重叠度分数的合并候选项列表。

4. 过时检查。 对索引中的每个条目： a. 查找最近的使用日志条目（任何操作类型）。 b. 计算距上次活动的天数。 c. 如果没有使用数据且条目质量为“untested”：标记为过时（未知——从未使用）。 d. 如果距上次活动 > 90 天（默认阈值）：标记为过时。 e. 如果距上次活动 > 90 天，但条目属于关键领域（security、compliance、incident-response）：改用 180 天的延长阈值。 f. 使用过时和证据过时是彼此独立的维度——条目可以处于活跃使用状态，同时引用过时的研究。请参阅下面的检查 8（证据时效性检查）；即使条目通过此项检查，也不要跳过该检查。 输出：过时条目列表，包含距上次活动的天数和建议操作。

5. 质量晋级检查。 对每个具有质量等级的条目： a. 统计使用日志中“loaded”操作的总数。 b. 检查使用日志中是否有任何“modified”操作。 c. 如果质量为“untested”且 loaded 次数 >= 5：建议晋级为“tested”。 d. 如果质量为“tested”且 loaded 次数 >= 10，且初始创建后没有“modified”操作：建议晋级为“iterated”。 e. 如果质量为“iterated”且 loaded 次数 >= 20，并且用户已明确审核：符合晋级为“curated”的条件（需要人工批准）。 f. 证据时效性问题（检查 8）不会阻止基于使用情况的晋级，但应与建议一并呈现——包含未经核实声明的晋级候选项仍需经过修正。 输出：晋级候选项列表，包含当前等级、建议等级和证据。

6. 孤立项检测。 对索引中的每个模板： a. 读取模板的 roles 数组。 b. 对每个角色名称：检查索引的 agents 数组中是否存在同名 Agent。 c. 如果未找到 Agent：标记为孤立引用。 输出：孤立引用列表，包含模板名称、缺失的 Agent 名称和严重程度。

7. 核心功能重叠检查。 对每个库条目： a. 将其与核心技能（mission-planner、agent-creator、skill-creator、librarian）进行比较。 b. 如果库条目所描述的功能与某项核心技能大幅重叠：标记为核心功能重叠。 输出：可能重复核心技能功能的条目列表。

8. 证据时效性检查。 证据基线：2026 年 7 月，目标模型为 Claude 4.5+/5。对此项检查适用于每个引用研究、提出定量声明或提供模型行为指导的条目，与上述基于使用情况的过时检查彼此独立。 对每个此类条目： a. 如果条目引用了来源：追溯 docs/research/source-index.md 中的引用。如果无法追溯：标记为未验证引用。 b. 如果条目提出了与引用相关的定量声明：确认该数字出现在所引用的来源中。如果没有：标记为缺乏依据的数字。 c. 如果条目将 Forge 约定（团队规模、词汇载荷数量、迭代上限、身份长度等）作为研究发现呈现，而未标注为约定：标记为错误标注的约定——建议明确标注为“Forge 设计标准”。 d. 如果条目包含超过约 18 个月的模型行为指导，且既未依据当前一代模型的证据重新确认，也未标注为“Forge 设计标准”：标记为需要重新确认。 e. 无论引用状态如何，都要检查两项当前模型指导规则（参见 references/review-criteria.md — Evidence Currency Criteria）： - 思维过程复述指令：该条目是否要求 Agent 叙述或打印其内部推理？如果是，予以标记。 - 规则堆砌：该条目是否用冗长的枚举规则列表取代简洁的目标／边界／验证框架？如果是，予以标记。 输出：证据时效性问题列表，注明条目名称、问题类型和建议的修复方案。这些是发现项，不是阻断项——参见第 9 步。

阶段 3：生成报告

9. 汇总审查报告。 将所有发现整理成结构化的 Markdown 报告（参见下方的输出格式）。 包括：

   • 摘要统计
   • 合并建议（说明保留哪个条目及原因）
   • 归档／删除建议（附原因和过时数据）
   • 质量提升建议（附使用情况证据）
   • 孤立引用（附修复选项）
   • 核心功能重叠警告
   • 证据时效性问题（附问题类型和建议的修复方案） 如果未发现问题：仅生成包含摘要统计的简洁报告。

10. 提交报告并等待用户批准。 在用户明确批准之前，切勿修改任何文件。 如果用户批准所有建议：继续执行阶段 4。 如果用户选择性批准：仅执行获批的更改。 如果用户拒绝：停止，不做任何更改。

阶段 4：执行变更

11. 执行已批准的变更。 对每项已批准的合并： a. 从 index.json 中移除质量较低的条目。 b. 可选：将已移除条目的独有标签复制到保留条目中。 c. 删除或归档已移除条目的文件。 对每项已批准的归档： a. 从 index.json 中移除该条目。 b. 将该条目的文件移至 library/archive/（如有需要则创建目录）。 对每项已批准的晋升： a. 更新 index.json 中该条目的 quality 字段。 对每项已批准的孤立引用修复： a. 按照指示更新 index.json 中模板的 roles 数组。 证据时效性修复属于内容编辑（更正某项声明、添加标签、重写充斥规则的指令），直接在条目文件中进行——它们在 index.json 中没有对应字段。 更新 index.json 的 updated 时间戳。

12. 记录所有变更。 对每项已执行的变更： 在 usage-log.jsonl 中追加一条记录，包含：

    • ts：当前 ISO 8601 时间戳
    • item：受影响条目的路径
    • type：条目类型（agent、skill、template）
    • action：移除时为 "archived"，晋升时为 "promoted"，合并、孤立引用修复和证据时效性修正时为 "modified"
    • context："librarian"

---

输出格式

审查报告采用结构化 Markdown：

# Library Review Report

**Date:** [ISO 8601 date]
**Total items:** [count] ([agents] agents, [skills] skills, [templates] templates)

## Summary Statistics

| Domain | Agents | Skills | Templates | Total |
|--------|--------|--------|-----------|-------|
| [domain] | [n] | [n] | [n] | [n] |
| ...    | ...    | ...    | ...       | ...   |

### Quality Distribution

| Tier | Count | Percentage |
|------|-------|------------|
| Curated | [n] | [%] |
| Iterated | [n] | [%] |
| Tested | [n] | [%] |
| Untested | [n] | [%] |

## Merge Candidates

### [Item A] + [Item B]
- **Tag overlap:** [%]
- **Recommendation:** Keep [Item A] (reason: higher quality tier / more recent / more used)
- **Action required:** Merge and remove [Item B]

## Archive Candidates

### [Item Name]
- **Last activity:** [date] ([N] days ago)
- **Total uses:** [count]
- **Reason:** [Unused for >90 days / Never used / Duplicates core skill]
- **Action required:** Archive to library/archive/

## Quality Promotions

### [Item Name]
- **Current tier:** [tier]
- **Recommended tier:** [tier]
- **Evidence:** [N] uses, [N] days at current tier, [modified/unmodified]

## Orphaned References

### Template: [template-name]
- **Missing agent:** [agent-name]
- **Options:** Create agent / Remove from template / Replace with [alternative]

## Evidence Currency Issues

### [Item Name]
- **Issue type:** [Unverified citation / Unsupported number / Mislabeled convention / Needs re-confirmation / Reasoning-echo instruction / Rule-stuffing]
- **Detail:** [what was found and where]
- **Recommended fix:** [trace or remove citation / correct the number / add "Forge design standard" label / re-confirm against current-generation evidence / remove the reasoning-echo instruction / replace with goal-boundary-verification framing]

## No Issues

[Only shown if all checks pass]
Library is clean. No merge candidates, stale items, promotions, orphans, or evidence-currency issues detected.

---

示例

示例 1：存在问题的知识库

场景： 知识库包含 12 个 agent、3 个 skill 和 2 个 template，涵盖软件和营销领域。

审查报告输出：

# Library Review Report

**Date:** 2026-03-28T12:00:00Z
**Total items:** 17 (12 agents, 3 skills, 2 templates)

## Summary Statistics

| Domain | Agents | Skills | Templates | Total |
|--------|--------|--------|-----------|-------|
| software | 8 | 2 | 1 | 11 |
| marketing | 4 | 1 | 1 | 6 |

### Quality Distribution

| Tier | Count | Percentage |
|------|-------|------------|
| Curated | 0 | 0% |
| Iterated | 1 | 8% |
| Tested | 3 | 25% |
| Untested | 8 | 67% |

## Merge Candidates

### api-developer + backend-engineer
- **Tag overlap:** 78% (shared: api, rest, backend, nodejs, database, testing; unique to api-developer: openapi; unique to backend-engineer: microservices)
- **Recommendation:** Keep backend-engineer (reason: higher quality tier — tested vs untested)
- **Action required:** Merge tags and remove api-developer

### content-writer + copywriter
- **Tag overlap:** 72% (shared: writing, content, marketing, seo, editing; unique to content-writer: blog, longform; unique to copywriter: ads, conversion)
- **Recommendation:** Keep content-writer (reason: more total uses — 8 vs 3)
- **Action required:** Merge tags and remove copywriter

## Archive Candidates

### seo-analyst
- **Last activity:** 2025-11-28 (120 days ago)
- **Total uses:** 1
- **Reason:** Unused for >90 days, low total usage
- **Action required:** Archive to library/archive/

## Quality Promotions

### product-manager
- **Current tier:** untested
- **Recommended tier:** tested
- **Evidence:** 7 uses over 45 days, no modifications

### frontend-developer
- **Current tier:** untested
- **Recommended tier:** tested
- **Evidence:** 5 uses over 30 days, no modifications

### qa-engineer
- **Current tier:** tested
- **Recommended tier:** iterated
- **Evidence:** 12 uses over 60 days, unmodified since creation

## Orphaned References

### Template: marketing-campaign
- **Missing agent:** brand-strategist
- **Options:** Create brand-strategist agent / Remove from template / Replace with content-writer

## Evidence Currency Issues

### backend-engineer
- **Issue type:** Unsupported number
- **Detail:** Agent definition claims "pair review catches three times as many defects" with no citation. No source in docs/research/source-index.md states this figure.
- **Recommended fix:** Remove the claim or replace with a sourced figure; if it describes a Forge convention, label it as such instead.

### qa-engineer
- **Issue type:** Reasoning-echo instruction
- **Detail:** SOP step 4 instructs the agent to "explain your step-by-step reasoning before giving the verdict."
- **Recommended fix:** Remove the reasoning-echo instruction; rely on adaptive thinking and require only the verdict plus supporting evidence.

示例 2：整洁的知识库

场景： 知识库包含 6 个 agent、1 个 skill 和 1 个 template。所有条目都在积极使用，没有重复项或孤立引用。

审查报告输出：

# Library Review Report

**Date:** 2026-03-28T12:00:00Z
**Total items:** 8 (6 agents, 1 skill, 1 template)

## Summary Statistics

| Domain | Agents | Skills | Templates | Total |
|--------|--------|--------|-----------|-------|
| software | 4 | 1 | 1 | 6 |
| marketing | 2 | 0 | 0 | 2 |

### Quality Distribution

| Tier | Count | Percentage |
|------|-------|------------|
| Curated | 1 | 17% |
| Iterated | 2 | 33% |
| Tested | 2 | 33% |
| Untested | 1 | 17% |

## No Issues

Library is clean. No merge candidates, stale items, promotions, orphans, or evidence-currency issues detected.

All items have been used within the last 90 days. Quality tiers are up to date. All template references resolve to existing agents. All citations trace to docs/research/source-index.md and no item shows reasoning-echo instructions or rule-stuffing.

---

环境分支

Claude Code 环境

• 直接操作文件系统。读取和写入 library/index.json、library/usage-log.jsonl 以及 library/ 下的条目文件。
• 通过就地修改文件来执行已批准的变更：更新 JSON、将文件移至 library/archive/、删除合并后的重复项。
• 如果 library/archive/ 目录不存在，则在首次归档时创建该目录。

Cowork / Claude.ai 环境

• 从工作文件夹读取内容。解析上传或可访问文件中的知识库索引和使用日志。
• 无法直接修改文件，而是生成包含具体建议的报告。
• 对于移除：建议通过 Customize 面板停用或移除哪些已安装的 skill。
• 对于晋升：提供更新后的 index.json 内容，供用户手动应用。
• 对于孤立引用修复：提供修正后的 template 定义，供用户手动更新。

---

此 Skill 回答的问题

当用户提出以下任何问题（或类似问题）时，此 skill 会激活：

• “审查知识库”
• “我的知识库里有什么？”
• “清理未使用的 agent/skill”
• “查找知识库中的重复项”
• “我有多少个 agent？”
• “哪些 agent 尚未使用？”
• “精简知识库”
• “显示知识库统计信息”
• “是否有孤立引用？”
• “晋升经过测试的 agent”
• “我的 agent 属于哪个质量等级？”
• “知识库中有没有过时内容？”
• “知识库中是否有引用过时研究的内容？”

---

参考资料

• ./references/review-criteria.md — 评分标准、阈值定义和合并策略详情
• ./schemas/index-schema.json — 知识库索引格式规范
• ./schemas/usage-log-schema.json — 使用日志条目格式规范
• docs/research/source-index.md — 证据时效性检查用于核实引用和定量声明的参考文献目录