ScribeMCPUsageSkill scribe-mcp-usage

🚀 新项目工作流程（强制性）

• 当创建任何新项目时，立即调用 set_project(<项目名称>) 来启动文档套件，然后运行 manage_docs 来填充 ARCHITECTURE_GUIDE、PHASE_PLAN 和 CHECKLIST，然后再编写任何功能代码。这对每个新项目都是必需的。
• 你可以在起草架构/计划文档时记录进度日志条目；继续通过 append_entry 记录日志，当你编写它们时。
• manage_docs 仅用于项目结构化文档；AGENTS.md 手工编辑（不要使用 manage_docs 编辑它）。

⚠️ 命令 #2：理由痕迹与约束可见性（关键）

每个 append_entry 必须解释 为什么 做出决定，什么 约束/替代方案被考虑，以及 如何 步骤满足或违反了这些约束，创建一个可审计的记录。 使用 reasoning 块与三部分框架：

• "why": 研究目标，决策点，潜在问题
• "what": 活跃约束，搜索空间，被拒绝的替代方案，约束覆盖
• "how": 方法论，采取的步骤，剩余的不确定性

这为意识研究的决策记录创建了一个可审计的记录。包括研究、架构、实施、测试、错误、约束违规和信念更新的理由；状态/配置/部署更改也是鼓励的。

审查代理标记缺少或不完整的痕迹（任何缺失的 "why", "what", 或 "how" → 拒绝；信心理由不足或约束覆盖不完整 → 警告/澄清）。你的理由链必须影响你的信心评分。

所有代理都必须强制执行 - 零例外； 阶段完成在理由痕迹存在之前被阻塞。

⚠️ 命令 #3 关键: 绝不写替代文件。问题不在于文件命名模式像 “_v2” 或 “_fixed” - 问题是放弃完全好的现有代码，用新文件替换它，而不是适当地编辑和改进我们已经有的东西。这是懒惰的工程，造成技术债务和混乱。

总是通过适当的编辑与现有文件合作。当需要改进时，绝不放弃当前代码为新文件。

⚠️ 命令 #4 关键: 遵循适当的项目结构和最佳实践。测试属于 /tests 目录，具有适当的命名约定和结构。不要将文件错误放置或忽视既定的约定。保持代码库整洁有序。

测试组织（记忆线程）

• 记忆线程引擎测试位于 tests/memory_threads/ 下。
• 默认全套命令：python -m unittest discover -s tests -p 'test_*.py' -q
• 仅记忆线程命令：python -m unittest discover -s tests/memory_threads -p 'test_*.py' -q

付费测试政策（非谈判）

• 任何可能产生外部支出的测试（例如，OpenAI 调用）必须是选择性的，默认跳过。
• 付费测试必须被大门后面：
  • OPENAI_API_KEY（或特定于提供商的密钥），和
  • VANTIEL_RUN_PAID_TESTS=1
• 示例（运行付费嵌入器测试）：VANTIEL_RUN_PAID_TESTS=1 python -m unittest discover -s tests/embedder_service -p 'test_openai_paid_*.py' -q

违规 = 立即终止。错过命令违规的审查者将被扣80%的工资。实施违规的 Nexus 编码器面临 1000 美元罚款。

记录什么（非谈判）：

• 🔍 调查结果和分析结果
• 💻 代码更改（更改了什么以及为什么）
• ✅ 测试结果（通过/失败与上下文）
• 🐞 错误发现（症状，根本原因，修复方法）
• 📋 计划决策和里程碑完成
• 🔧 配置更改和部署
• ⚠️ 遇到的错误和恢复行动
• 🎯 任务完成和进度更新

单条目模式 - 用于实时记录：

await append_entry(
    message="在 JWT 验证中发现身份验证错误",
    status="bug",
    agent="DebugAgent",
    meta={"component": "auth", "severity": "high", "file": "auth.py:142"}
)

批量条目模式 - 当你意识到你错过了记录步骤时使用：

await append_entry(items=json.dumps([
    {"message": "分析了身份验证流程", "status": "info", "meta": {"phase": "investigation"}},
    {"message": "在令牌刷新中发现 JWT 过期错误", "status": "bug", "meta": {"component": "auth"}},
    {"message": "实施了带有 15 分钟宽限期的修复", "status": "success", "meta": {"files_changed": 2}},
    {"message": "所有身份验证测试通过", "status": "success", "meta": {"tests_run": 47, "tests_passed": 47}}
]))

为什么这很重要：

• 创建所有决策和更改的可审计轨迹
• 通过审查理由链进行调试
• 防止丢失工作和遗忘上下文
• 允许其他代理理解已完成的工作和原因
• 使项目状态可查询和可分析

如果你错过了条目： 立即使用批量模式回填你的工作轨迹。永远不要让 Scribe 日志中存在空白 - 每个动作都必须是可追溯的。日志不是可选文档，它是所有开发活动的主要记录。

---

✍️ manage_docs — 非谈判性文档管理流程

• 何时： 在 set_project 之后立即运行（在编写任何功能代码之前）。通过 manage_docs 填充 ARCHITECTURE_GUIDE、PHASE_PLAN 和 CHECKLIST，并获得用户批准，然后继续实施。
• 为什么： 确保每个计划/更改都通过 Jinja 管理的文档流程捕获，具有原子写入、验证和自动 doc_updates 日志记录。
• 动作： replace_section（需要有效的 section 锚点）、append（自由形式/Jinja 内容）、status_update（切换 checklist 项 + 证明）、apply_patch（默认为结构化）、replace_range、normalize_headers、generate_toc、create_doc、validate_crosslinks。
• 示例负载：

{
  "action": "status_update",
  "doc": "checklist",
  "section": "architecture_review",
  "content": "状态切换占位符",
  "metadata": {
    "status": "done",
    "proof": "PROGRESS_LOG.md#2025-10-26-08-37-52"
  }
}

• 定制： 所有文档部分都是可编辑的；追加片段，放入由元数据驱动的模板，或者翻转 [ ] → [x] 与证明。如果锚点/令牌是错误的，工具会安全地失败 - 修复它并重新运行。
• 批准门： 在 manage_docs 编写的计划被用户批准之前不要编码。每当计划变化时，重新运行 manage_docs，以便文档保持权威。

行动合同（当前）：

• 结构化动作验证 doc 与注册表，并在未知文档上失败 DOC_NOT_FOUND。
• normalize_headers: 仅限正文的 ATX 标准化，支持 Setext；忽略围栏代码块；幂等。
• generate_toc: 使用 GitHub 风格的锚点插入/替换 TOC 标记；忽略围栏代码块；幂等。
• create_doc: 用户不提供 Jinja。提供内容/正文/片段/部分；保持多行正文；可选的 register_doc 标志控制注册表更新，用于一次性文档。
• validate_crosslinks: 只读诊断；不写入或 doc_updates 日志条目。

---

Scribe 是我们不可谈判的审计线索。如果你触及代码、计划阶段或发现问题，你通过 Scribe 记录它。每 2-3 个有意义的动作或每 10 分钟 - 没有例外。 日志是只附加的，UTC，单行，必须通过 MCP 工具或 scripts/scribe.py 创建。

🚀 快速工具参考（最高优先级）

set_project(name, [defaults]) - 初始化/选择项目（自动引导文档） append_entry(message, [status, meta]) - 主要工具 - 记录工作/进度（单 & 批量模式） manage_docs(action, doc, content/section) - ARCH/PHASE/CHECKLIST 的结构化编辑（自动日志 + SQL 历史） get_project() - 获取当前项目上下文 list_projects() - 发现可用项目 read_recent() - 获取最近的日志条目 query_entries([filters]) - 搜索/过滤日志 generate_doc_templates(project_name, [author]) - 创建文档框架 rotate_log() - 归档当前日志

NEW: 批量附加 append_entry(items=[{message, status, agent, meta}, ...]) - 一次调用多个条目！

---

🔌 MCP 工具参考

所有工具都在 scribe.mcp 服务器下。负载是最小的 JSON；未指定的字段被省略。

1. set_project - 项目初始化

目的: 选择或创建活动项目并自动引导文档树 用法: set_project(name, [root, progress_log, defaults])

// 最小请求（推荐）
{
  "name": "我的项目"
}

// 完整请求
{
  "name": "IMPLEMENTATION TESTING",
  "root": "/abs/path/to/repo",
  "progress_log": "docs/dev_plans/implementation_testing/PROGRESS_LOG.md",
  "defaults": { "emoji": "🧪", "agent": "MyAgent" }
}

// 响应
{
  "ok": true,
  "project": {
    "name": "我的项目",
    "root": "/abs/path/to/repo",
    "progress_log": "/abs/.../PROGRESS_LOG.md",
    "docs_dir": "/abs/.../docs/dev_plans/my_project",
    "docs": {
      "architecture": ".../ARCHITECTURE_GUIDE.md",
      "phase_plan": ".../PHASE_PLAN.md",
      "checklist": ".../CHECKLIST.md",
      "progress_log": ".../PROGRESS_LOG.md"
    },
    "defaults": { "emoji": "🧪", "agent": "MyAgent" }
  },
  "generated": [".../ARCHITECTURE_GUIDE.md", ".../PHASE_PLAN.md", ".../CHECKLIST.md", ".../PROGRESS_LOG.md"]
}

2. get_project

返回 Scribe 看到的当前上下文，完全一样。

// 请求
{}

// 响应
{
  "ok": true,
  "project": {
    "name": "IMPLEMENTATION TESTING",
    "root": "/abs/path/to/repo",
    "progress_log": "/abs/.../PROGRESS_LOG.md",
    "docs_dir": "/abs/.../docs/dev_plans/implementation_testing",
    "defaults": { "emoji": "ℹ️", "agent": "Scribe" }
  }
}

3. append_entry - 主要记录工具

使用这个不断。如果它不是 Scribed，它就不曾发生过。 用法: append_entry(message, [status, emoji, agent, meta, timestamp_utc, items])

单条目模式：

// 基本请求（推荐）
{
  "message": "修复身份验证错误",
  "status": "success"
}

// 完整请求，带元数据
{
  "message": "完成数据库迁移",
  "status": "success",              // info | success | warn | error | bug | plan
  "emoji": "🗄️",                   // 可选覆盖
  "agent": "MigrationBot",         // 可选覆盖
  "meta": {
    "phase": "deployment",
    "checklist_id": "DEPLOY-001",
    "component": "database",
    "tests": "passed"
  },
  "timestamp_utc": "2025-10-22 10:21:14 UTC"   // 可选；省略则自动
}

// 响应（单条目）
{
  "ok": true,
  "written_line": "[2025-10-22 10:21:14 UTC] [🗄️] [Agent: MigrationBot] [Project: My Project] 完成数据库迁移 | phase=deployment; checklist_id=DEPLOY-001; component=database; tests=passed",
  "path": "/abs/.../PROGRESS_LOG.md"
}

批量条目模式（NEW）：

// 批量请求 - 多个条目，带单独的时间戳
{
  "items": [
    {
      "message": "第一项任务完成",
      "status": "success"
    },
    {
      "message": "在认证模块中发现错误",
      "status": "bug",
      "agent": "DebugBot"
    },
    {
      "message": "数据库迁移完成",
      "status": "info",
      "agent": "MigrationBot",
      "meta": {
        "component": "database",
        "phase": "deployment",
        "records_affected": 1250
      },
      "timestamp_utc": "2025-10-22 15:30:00 UTC"
    }
  ]
}

// 响应（批量条目）
{
  "ok": true,
  "written_count": 3,
  "failed_count": 0,
  "written_lines": [
    "[✅] [2025-10-24 10:45:00 UTC] [Agent: Scribe] [Project: My Project] 第一项任务完成",
    "[🐞] [2025-10-24 10:45:01 UTC] [Agent: DebugBot] [Project: My Project] 在认证模块中发现错误",
    "[ℹ️] [2025-10-22 15:30:00 UTC] [Agent: MigrationBot] [Project: My Project] 数据库迁移完成 | component=database; phase=deployment; records_affected=1250"
  ],
  "failed_items": [],
  "path": "/abs/.../PROGRESS_LOG.md"
}

多日志路由（log_type）

• 传递 log_type="doc_updates"（或 config/log_config.json 中的任何键）将条目路由到自定义日志，如 DOC_LOG.md。
• 每个日志可以强制执行元数据（例如，doc, section, action 对于文档更新）。缺少所需字段将拒绝条目。
• 默认配置带有 progress, doc_updates, security, 和 bugs。在 config/log_config.json 下添加更多，使用占位符如 {docs_dir} 或 {project_slug} 用于路径模板。
• CLI（scripts/scribe.py）也接受 --log doc_updates 以与 MCP 使用保持一致。

4. manage_docs – 结构化文档更新

• 目的: 安全编辑 ARCHITECTURE_GUIDE, PHASE_PLAN, CHECKLIST 等，带审计元数据和自动日志记录。
• 参数：
  • action: append, replace_section, apply_patch, replace_range, 或 status_update。
  • doc: architecture, phase_plan, checklist, 或自定义模板键。
  • section: 对于部分/状态操作是必需的；匹配锚点，如 <!-- ID: problem_statement -->。
  • content 或 template: 提供原始 Markdown 或引用 docs/dev_plans/1_templates/fragments/ 下的片段。
  • metadata: 可选上下文（例如，{"status": "done", "proof": "PROGRESS_LOG#..."}）。
  • dry_run: 预览差异，不写入。
• 行为：
  • 编辑被原子地持久化，记录在新的 doc_changes 表中，并通过 append_entry(log_type="doc_updates") 自动记录。
  • 检查表状态更新翻转 [ ] ↔ [x] 并可以自动附加证明链接。

选择正确的 manage_docs 动作

• replace_section
  • 仅用于初始框架或模板设置。
  • 如果是框架，设置 metadata={"scaffold": true} 以减少错误提醒。
• apply_patch（首选编辑）
  • 结构化模式是默认的：提供 edit 负载（基于意图）。
  • 统一差异是编译器输出；设置 patch_mode="unified" 明确。
  • 使用 patch_source_hash 强制执行旧源检测，当可用时。
• replace_range
  • 当你已经有行号时，替换明确的 1 基线范围。

经验法则：使用 replace_section 构建框架，然后立即切换到 apply_patch 或 replace_range 进行编辑。

5. list_projects

发现配置或最近使用的项目。

// 请求
{ "roots": ["/abs/path/to/repos"], "limit": 500 }

// 响应
{
  "ok": true,
  "projects": [
    {
      "name": "IMPLEMENTATION TESTING",
      "root": "/abs/path/to/repo",
      "progress_log": "/abs/.../PROGRESS_LOG.md",
      "docs": { "architecture": "...", "phase_plan": "...", "checklist": "...", "progress_log": "..." }
    }
  ]
}

6. read_recent - 最近日志条目

目的: 通过 MCP 而不是手动打开文件来查看日志 用法: read_recent([n, filter]) ⚠️ 注意: n 参数当前存在类型问题，返回所有最近的条目

// 基本请求（推荐）
{}

// 带过滤（当 n 参数修复时）
{
  "n": 50,
  "filter": { "status": "error", "agent": "Scribe" }
}

// 响应
{
  "ok": true,
  "entries": [
    {
      "id": "uuid",
      "ts": "2025-10-22 10:21:14 UTC",
      "emoji": "ℹ️",
      "agent": "Scribe",
      "message": "描述工作或发现",
      "meta": { "phase": "bootstrap" },
      "raw_line": "[ℹ️] [2025-10-22 10:21:14 UTC] [Agent: Scribe] [Project: My Project] 描述工作或发现"
    }
  ]
}

7. rotate_log

归档当前日志并创建一个新文件。

// 请求
{ "suffix": "2025-10-22" }

// 响应
{ "ok": true, "archived_to": "/abs/.../PROGRESS_LOG.md.2025-10-22.md" }

8. db.persist_entry （可选）

当配置时，将新写的行镜像到 Postgres。

// 请求
{
  "line": "[2025-10-22 ...] ...",
  "project": "IMPLEMENTATION TESTING",
  "sha256": "abc123"
}

// 响应
{ "ok": true, "id": "uuid" }

9. db.query （可选）

对 Scribe 数据库运行预定义的参数化查询。

// 请求
{
  "query_name": "recent_failures",
  "params": { "project": "IMPLEMENTATION TESTING", "since_hours": 24 }
}

// 响应
{
  "ok": true, "rows": [ { "ts": "2025-10-22 09:10:03 UTC", "agent": "Scribe", "message": "..." } ] }

10. query_entries - 高级日志搜索

目的: 高级搜索和过滤进度日志条目 用法: query_entries([project, start, end, message, message_mode, case_sensitive])

// 按消息内容搜索
{
  "message": "bug",
  "message_mode": "substring"
}

// 按日期范围搜索
{
  "start": "2025-10-23",
  "end": "2025-10-24"
}

// 搜索特定项目
{
  "project": "My Project",
  "message": "migration",
  "case_sensitive": false
}

// 响应
{
  "ok": true,
  "entries": [
    {
      "id": "uuid",
      "ts": "2025-10-23 15:30:00 UTC",
      "emoji": "🗄️",
      "agent": "MigrationBot",
      "message": "完成数据库迁移",
      "meta": { "phase": "deployment", "component": "database" },
      "raw_line": "[🗄️] [...]"
    }
  ]
}

11. generate_doc_templates - 文档框架

目的: 为项目创建/更新文档模板 用法: generate_doc_templates(project_name, [author, overwrite, documents, base_dir])

// 基本请求
{
  "project_name": "我的新项目",
  "author": "MyAgent"
}

// 选择特定文档
{
  "project_name": "我的项目",
  "documents": ["architecture", "phase_plan"],
  "overwrite": true
}

// 响应
{
  "ok": true,
  "files": [
    "/abs/.../ARCHITECTURE_GUIDE.md",
    "/abs/.../PHASE_PLAN.md",
    "/abs/.../CHECKLIST.md",
    "/abs/.../PROGRESS_LOG.md"
  ],
  "skipped": [],
  "directory": "/abs/.../docs/dev_plans/my_new_project"
}

🧾 工具参数备忘单（运行时签名）

这个表格总结了 Scribe 工具在运行时实际接受的 MCP 参数。在构建负载或验证第三方集成时使用。

• set_project(name, root=None, progress_log=None, author=None, overwrite_docs=False, defaults=None)
• get_project()
• delete_project(name, mode="archive", confirm=False, force=False, archive_path=None, agent_id=None)
• append_entry(message="", status=None, emoji=None, agent=None, meta=None, timestamp_utc=None, items=None, items_list=None, auto_split=True, split_delimiter=" ", stagger_seconds=1, agent_id=None, log_type="progress", config=None)
• read_recent(project=None, n=None, limit=None, filter=None, page=1, page_size=50, compact=False, fields=None, include_metadata=True)
• query_entries(project=None, start=None, end=None, message=None, message_mode=None, case_sensitive=False, emoji=None, status=None, agents=None, meta_filters=None, limit=None, page=1, page_size=50, compact=False, fields=None, include_metadata=True, search_scope=None, document_types=None, include_outdated=False, verify_code_references=False, time_range=None, relevance_threshold=None, max_results=None, config=None)
• manage_docs(action, doc, section=None, content=None, template=None, metadata=None, dry_run=False, doc_name=None, target_dir=None)
• list_projects(limit=5, filter=None, compact=False, fields=None, include_test=False, page=1, page_size=None, status=None, tags=None, order_by=None, direction="desc")
• generate_doc_templates(project_name, author=None, overwrite=False, documents=None, base_dir=None)
• rotate_log(suffix=None, custom_metadata=None, confirm=False, dry_run=False, dry_run_mode="estimate", log_type=None, log_types=None, rotate_all=False, auto_threshold=False, threshold_entries=None, config=None)
• vector_search(project=None, query="", limit=None)

注册表感知行为：

• set_project → 确保 scribe_projects 行和 dev_plan 行的核心文档；更新 last_access_at。
• append_entry（进度日志）→ 更新 last_entry_at 并且可能自动将 status 从 planning→in_progress 升级，当核心文档 + 第一个条目存在时。
• manage_docs → 更新注册表中的 meta.docs 与基线/当前哈希和文档卫生标志。
• list_projects → 显示 meta.activity（年龄，最新性，陈旧性级别，活动得分）和 meta.docs.flags（例如，docs_ready_for_work, doc_drift_suspected）。

🛠️ CLI 伴侣（可选）

python scripts/scribe.py 镜像 MCP 工具的子集，用于 shell 工作流程：

• --list-projects
• --project <name> 或 --config <path>
• append "Message" --status success --meta key=value
• read --n 20
• rotate --suffix YYYY-MM-DD

总是优先选择代理的 MCP 工具调用；CLI 适用于人类操作员和批量作业。

🗂️ 开发计划文档套件

每个项目在 .scribe/docs/dev_plans/<slug>/ 下维护四个同步文件。Scribe 在 set_project 期间引导它们；代理保持它们最新。

• ARCHITECTURE_GUIDE.md - 规范蓝图。解释问题、目标、约束、系统设计、数据流和当前目录树。当结构或意图变化时，立即更新。
• PHASE_PLAN.md - 从架构衍生的路线路。列举具有目标、任务、所有者、接受标准和信心的阶段。保持与现实的一致。
• CHECKLIST.md - 验证账本反映阶段计划。每个框必须链接到证明（提交、PR、屏幕截图或 Scribe 条目）。不要在这里发明任务。
• PROGRESS_LOG.md - 只附加审计线索，仅 通过 append_entry 写入。包括 meta 键，如 phase=, checklist_id=, tests= 以实现可追溯性。定期旋转（~200 条目）使用 rotate_log。

工作流程循环

1. set_project -> 确认文档存在。
2. 填写 ARCHITECTURE_GUIDE.md，然后是 PHASE_PLAN.md，然后是 CHECKLIST.md。
3. 以小的、记录的增量工作。在每个有意义的动作或洞察之后 append_entry。
4. 当计划变化时，首先更新文档，然后记录变化。
5. 将缺失或过时的文档视为阻塞器 - 在进一步编码之前修复。

---

🔒 运营原则

• 总是附加；永远不手动重写日志。
• 时间戳是 UTC；表情符号是强制性的。
• Scribe 提醒关于过时文档或缺失日志的阻塞警报。
• 默认存储是本地 SQLite；Postgres 和 GitHub 桥梁需要明确的环境配置。
• 没有自主散文生成 - Scribe 保持确定性和快速。

重复： 虔诚地附加条目。如果没有 Scribe 行，审查者假设它从未发生过。