docs(i18n): add agent team playbook and enforce EN-first parity

rexleimo · rexleimo · commit 4c775ad2eb7a · 2026-04-08T22:03:05.000+08:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,6 +23,7 @@ jobs:
         run: |
           python3 -m unittest \
             scripts.tests.test_ci_workflows \
+            scripts.tests.test_check_i18n_parity \
             scripts.tests.test_check_openharness_upstream \
             scripts.tests.test_verify_version_changelog \
             scripts.tests.test_verify_release_consistency \
diff --git a/README.md b/README.md
@@ -15,6 +15,7 @@ LoopForge  is a **personal AI engineer** for software delivery: long-running wor
 - Docs site: https://os.rexai.top
 - (If the custom domain isn’t configured yet) GitHub Pages: https://rexleimo.github.io/LoopForge/
 - 5-minute outcomes: `docs-site/tutorials/five-minute-outcomes.md`
+- Agent Team playbook: `docs-site/how-to/agent-team-playbook.md`
 - Positioning: `docs-site/explanation/why-loopforge.md`
 - Runtime architecture: `docs-site/explanation/runtime-architecture.md`
 - Internal maintainer map: `docs/internal/runtime-module-map.md`
@@ -74,6 +75,17 @@ After onboarding, LoopForge writes:
 - `loopforge-onboard-demo/.loopforge/onboard-report.json`
 - `loopforge-onboard-demo/.loopforge/onboard-report.md`
 
+## Agent Team mode (recommended for teams)
+
+Treat LoopForge as a compact agent team with clear ownership:
+
+- Planner agent: breaks down scope, risks, and acceptance criteria into `notes/plan.md`
+- Builder agent: ships implementation and runs verification gates
+- Reviewer agent: runs findings-first review and writes `notes/review.md`
+- Release agent: runs `loopforge release check` and prepares cap/release actions
+
+Playbook: `docs-site/how-to/agent-team-playbook.md`
+
 ## Run with Ollama (OpenAI-compatible)
 
 LoopForge defaults to `ollama` at `http://127.0.0.1:11434/v1` in `~/.loopforge/config.toml`.
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -15,6 +15,7 @@ LoopForge是一个面向软件交付的 **个人研发助理（Personal AI Engin
 - 文档站点：https://os.rexai.top
 - （如自定义域名未配置）GitHub Pages：https://rexleimo.github.io/LoopForge/
 - 5 分钟可见结果：`docs-site/tutorials/five-minute-outcomes.md`
+- Agent Team 作战手册：`docs-site/how-to/agent-team-playbook.md`
 - 产品定位说明：`docs-site/explanation/why-loopforge.md`
 - 运行时架构说明：`docs-site/explanation/runtime-architecture.md`
 - 仓库内部维护者地图：`docs/internal/runtime-module-map.md`
@@ -66,6 +67,17 @@ loopforge agent run --workspace /tmp/loopforge-work --prompt "Create hello.txt w
 可选的 Ollama smoke test：`LOOPFORGE_OLLAMA_MODEL=<your-model> cargo test --workspace --test ollama_smoke -- --ignored`。
 可选的 NVIDIA NIM smoke test：`NVIDIA_API_KEY=<key> cargo test --workspace --test nvidia_nim_smoke -- --ignored`。
 
+## Agent Team 模式（团队推荐）
+
+把 LoopForge 当作一个“小型 Agent Team”来用，并明确分工：
+
+- Planner Agent：拆解范围、风险和验收标准，沉淀到 `notes/plan.md`
+- Builder Agent：完成实现并执行验证门禁
+- Reviewer Agent：做 findings-first 评审，输出 `notes/review.md`
+- Release Agent：执行 `loopforge release check`，准备 cap/发版动作
+
+操作手册：`docs-site/how-to/agent-team-playbook.md`
+
 ## 发版（维护者）
 
 推送一个 `v*` tag 仍然会触发 Release 工作流，构建并把预编译压缩包上传到 GitHub Release。
diff --git a/docs-site/how-to/agent-team-playbook.md b/docs-site/how-to/agent-team-playbook.md
@@ -0,0 +1,63 @@
+# Agent Team Playbook
+
+LoopForge is most effective when you run it as an **agent team**, not a single long chat thread.
+
+This page gives you a practical team operating model you can demo and reuse.
+
+## Team Topology
+
+| Role | Primary output | Suggested artifact |
+|---|---|---|
+| Planner Agent | Scope, milestones, risk map | `notes/plan.md` |
+| Builder Agent | Verified implementation | code diff + test output |
+| Reviewer Agent | Findings-first review | `notes/review.md` |
+| Release Agent | Release readiness + publish gate | `notes/release-check.md` |
+
+## Operating Loop
+
+1. Intake and planning
+   - Capture objective, constraints, and acceptance criteria.
+   - Run one planning task and write `notes/plan.md`.
+2. Execution
+   - Build in small slices and checkpoint each verified slice.
+   - Keep one artifact per slice (report, checklist, or fix memo).
+3. Review
+   - Run findings-first review before merge/release.
+   - Record severity, impacted files, and decision.
+4. Release gate
+   - Run `loopforge release check --tag vX.Y.Z`.
+   - Ensure version/changelog/CI gates are green before publish.
+
+## Command Baseline
+
+```bash
+# bootstrap
+loopforge onboard --workspace loopforge-team-demo --starter workspace-brief
+
+# builder execution
+loopforge agent run --workspace loopforge-team-demo --prompt "Implement task from notes/plan.md"
+
+# release gate
+loopforge release check --tag v1.3.0
+```
+
+## Copy/Paste Role Prompts
+
+- Planner: "Create a 5-step implementation plan with risks and verification commands. Write `notes/plan.md`."
+- Builder: "Execute step 1 from `notes/plan.md`, keep behavior unchanged, and output a short verification report."
+- Reviewer: "Review current diff with findings first (severity + file/line), then list residual risks."
+- Release: "Run release readiness checks and write `notes/release-check.md` with pass/fail per gate."
+
+## What To Show In Team Demos
+
+- Time to first verified artifact
+- Verification pass rate per slice
+- Release-check pass/fail trend
+
+If those three metrics improve, your agent team is getting stronger in the right way.
+
+## Next Links
+
+- [Harness long task workflow](../tutorials/harness-long-task.md)
+- [Case task library](../examples/case-tasks/index.md)
+- [Release readiness audit task](../examples/case-tasks/release-readiness-audit.md)
diff --git a/docs-site/how-to/use-cases.md b/docs-site/how-to/use-cases.md
@@ -16,6 +16,7 @@ If you want a quick path, start here:
 - [Setup Sanity Check](../examples/sanity-check.md)
 - [Case Tasks (Copy/Paste)](../examples/case-tasks/index.md)
 - [Harness Recipes (Checkpoints)](../examples/harness-recipes.md)
+- [Agent Team Playbook](agent-team-playbook.md)
 - [Mechanical Edits](../examples/mechanical-edits.md)
 - [Routing Recipes](../examples/routing-recipes.md)
 - [Daemon Health Check](../examples/daemon-health.md)
diff --git a/docs-site/index.md b/docs-site/index.md
@@ -63,6 +63,10 @@ These files tell you what passed, what failed, and what to do next.
   Keep a clear trail: change -> verify -> checkpoint.
   [Harness workflow](tutorials/harness-long-task.md)
 
+- :material-account-group: **Agent Team Playbook**
+  Organize Planner / Builder / Reviewer / Release roles with one artifact trail.
+  [Open playbook](how-to/agent-team-playbook.md)
+
 - :material-sitemap: **Runtime Architecture**
   Understand how CLI, runtime, tools, memory, and audits fit together.
   [Open architecture guide](explanation/runtime-architecture.md)
@@ -81,5 +85,6 @@ These files tell you what passed, what failed, and what to do next.
 - [Starter tasks](tutorials/first-day-starter-tasks.md)
 - [Onboarding troubleshooting](how-to/onboarding-troubleshooting.md)
 - [5-minute outcomes](tutorials/five-minute-outcomes.md)
+- [Agent Team playbook](how-to/agent-team-playbook.md)
 - [Case task library](examples/case-tasks/index.md)
 - [Runtime architecture](explanation/runtime-architecture.md)
diff --git a/docs-site/zh-CN/blog/agent-memory-design.md b/docs-site/zh-CN/blog/agent-memory-design.md
@@ -0,0 +1,10 @@
+# 为什么你的 AI 助手记不住上下文？Agent 记忆设计指南
+
+> 本页按 EN 源文档同步维护。当前内容请先阅读英文目录中的同名页面（内容一致，后续以 EN 基线持续补齐多语言版本）。
+
+- 英文源页面：[`docs-site/blog/agent-memory-design.md`](../../blog/agent-memory-design.md)
+
+如果你正在评估 LoopForge 的记忆体系，建议配合阅读：
+
+- [概念与记忆模型](../explanation/concepts.md)
+- [Harness 长任务执行](../tutorials/harness-long-task.md)
diff --git a/docs-site/zh-CN/blog/index.md b/docs-site/zh-CN/blog/index.md
@@ -5,6 +5,9 @@
 ## 最新文章
 
 - [LoopForge v1.0.0 发布说明](loopforge-v1-0-0-release-notes.md)
+- [5分钟学会 MCP：让 AI Agent 真正掌控你的开发环境](mcp-integration-guide.md)
+- [为什么你的 AI 助手记不住上下文？Agent 记忆设计指南](agent-memory-design.md)
+- [让 AI 放心执行代码：隔离执行环境的最佳实践](safe-code-execution.md)
 - [LoopForge：不是泛助手，而是个人研发助理](personal-ai-engineer.md)
 - [什么是 LoopForge？](what-is-loopforge.md)
 
diff --git a/docs-site/zh-CN/blog/mcp-integration-guide.md b/docs-site/zh-CN/blog/mcp-integration-guide.md
@@ -0,0 +1,10 @@
+# 5分钟学会 MCP：让 AI Agent 真正掌控你的开发环境
+
+> 本页按 EN 源文档同步维护。当前内容请先阅读英文目录中的同名页面（内容一致，后续以 EN 基线持续补齐多语言版本）。
+
+- 英文源页面：[`docs-site/blog/mcp-integration-guide.md`](../../blog/mcp-integration-guide.md)
+
+配套建议阅读：
+
+- [Quickstart（Ollama）](../tutorials/quickstart-ollama.md)
+- [MCP 诊断命令参考](../reference/cli.md)
diff --git a/docs-site/zh-CN/blog/safe-code-execution.md b/docs-site/zh-CN/blog/safe-code-execution.md
@@ -0,0 +1,10 @@
+# 让 AI 放心执行代码：隔离执行环境的最佳实践
+
+> 本页按 EN 源文档同步维护。当前内容请先阅读英文目录中的同名页面（内容一致，后续以 EN 基线持续补齐多语言版本）。
+
+- 英文源页面：[`docs-site/blog/safe-code-execution.md`](../../blog/safe-code-execution.md)
+
+配套建议阅读：
+
+- [安全与沙盒](../explanation/security.md)
+- [工具参考](../reference/tools.md)
diff --git a/docs-site/zh-CN/how-to/agent-team-playbook.md b/docs-site/zh-CN/how-to/agent-team-playbook.md
@@ -0,0 +1,63 @@
+# Agent Team 作战手册
+
+LoopForge 在团队里的最佳用法，不是“单线程长对话”，而是按 **Agent Team 分工**协作。
+
+这页给出一个可复用、可演示的团队运行模型。
+
+## 团队分工拓扑
+
+| 角色 | 核心输出 | 建议产物 |
+|---|---|---|
+| Planner Agent | 范围、里程碑、风险图 | `notes/plan.md` |
+| Builder Agent | 通过验证的实现 | 代码 diff + 测试结果 |
+| Reviewer Agent | findings-first 评审结论 | `notes/review.md` |
+| Release Agent | 发布就绪与门禁结果 | `notes/release-check.md` |
+
+## 运行闭环
+
+1. 需求接入与规划
+   - 明确目标、约束、验收标准。
+   - 先产出 `notes/plan.md`。
+2. 分片执行
+   - 小步实现，每片都做验证并 checkpoint。
+   - 每片至少沉淀一个产物（报告、检查单、修复记录）。
+3. 评审
+   - 合并或发布前执行 findings-first 评审。
+   - 记录严重级别、影响文件、处理决策。
+4. 发布门禁
+   - 执行 `loopforge release check --tag vX.Y.Z`。
+   - 版本号、changelog、CI 全绿再发布。
+
+## 命令基线
+
+```bash
+# 启动与对齐
+loopforge onboard --workspace loopforge-team-demo --starter workspace-brief
+
+# Builder 执行
+loopforge agent run --workspace loopforge-team-demo --prompt "Implement task from notes/plan.md"
+
+# 发布门禁
+loopforge release check --tag v1.3.0
+```
+
+## 可复制角色 Prompt
+
+- Planner："给出 5 步实现计划，包含风险和验证命令，写入 `notes/plan.md`。"
+- Builder："执行 `notes/plan.md` 的第 1 步，保持行为不变，并输出简短验证报告。"
+- Reviewer："对当前 diff 做 findings-first 评审（严重级别 + 文件/行），再列剩余风险。"
+- Release："执行发布就绪检查，并把每个门禁的 pass/fail 写入 `notes/release-check.md`。"
+
+## 团队演示建议展示的 3 个指标
+
+- 首个“已验证产物”的产出时长
+- 每个分片的验证通过率
+- release-check 通过率趋势
+
+这三项提升，通常意味着 Agent Team 产能和稳定性都在同步提升。
+
+## 下一步阅读
+
+- [Harness 长任务工作流](../tutorials/harness-long-task.md)
+- [案例任务库](../examples/case-tasks/index.md)
+- [发布就绪审计任务](../examples/case-tasks/release-readiness-audit.md)
diff --git a/docs-site/zh-CN/how-to/use-cases.md b/docs-site/zh-CN/how-to/use-cases.md
@@ -16,6 +16,7 @@
 - [环境自检](../examples/sanity-check.md)
 - [案例任务（可复制粘贴）](../examples/case-tasks/index.md)
 - [Harness 配方（Checkpoints）](../examples/harness-recipes.md)
+- [Agent Team 作战手册](agent-team-playbook.md)
 - [机械化改动](../examples/mechanical-edits.md)
 - [路由示例](../examples/routing-recipes.md)
 - [Daemon 健康检查](../examples/daemon-health.md)
diff --git a/docs-site/zh-CN/index.md b/docs-site/zh-CN/index.md
@@ -63,6 +63,10 @@ LoopForge 的定位是工程交付型 AI 助理：本地优先、产物导向、
   固化流程：修改 -> 验证 -> checkpoint。
   [Harness 工作流](tutorials/harness-long-task.md)
 
+- :material-account-group: **Agent Team 作战手册**
+  用 Planner / Builder / Reviewer / Release 分工，统一产物轨迹。
+  [打开手册](how-to/agent-team-playbook.md)
+
 - :material-sitemap: **运行时架构**
   快速理解 CLI、runtime、tools、memory 与 audit 是如何衔接的。
   [打开架构说明](explanation/runtime-architecture.md)
@@ -81,5 +85,6 @@ LoopForge 的定位是工程交付型 AI 助理：本地优先、产物导向、
 - [Starter Tasks](tutorials/first-day-starter-tasks.md)
 - [上手排障](how-to/onboarding-troubleshooting.md)
 - [5 分钟可见结果](tutorials/five-minute-outcomes.md)
+- [Agent Team 作战手册](how-to/agent-team-playbook.md)
 - [案例任务库](examples/case-tasks/index.md)
 - [运行时架构](explanation/runtime-architecture.md)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -77,6 +77,7 @@ plugins:
             Beginner FAQ: 新手 FAQ
             Workflows: 工作流
             Long Task With Harness: Harness 长任务
+            Agent Team Playbook: Agent Team 作战手册
             Examples: 案例代码
             Common Use Cases: 常见场景
             Case Tasks: 案例任务
@@ -182,6 +183,7 @@ nav:
           - Beginner FAQ: how-to/faq.md
       - Workflows:
           - Long Task With Harness: tutorials/harness-long-task.md
+          - Agent Team Playbook: how-to/agent-team-playbook.md
           - Browser Automation: how-to/browser-automation.md
       - Configuration:
           - Providers & Routing: how-to/providers.md
diff --git a/scripts/check_i18n_parity.py b/scripts/check_i18n_parity.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def resolve_repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def collect_base_markdown_files(docs_root: Path, locale: str) -> list[Path]:
+    out: list[Path] = []
+    for path in docs_root.rglob("*.md"):
+        rel = path.relative_to(docs_root)
+        if rel.parts and rel.parts[0] == locale:
+            continue
+        out.append(rel)
+    out.sort()
+    return out
+
+
+def collect_missing_translations(docs_root: Path, locale: str) -> list[Path]:
+    missing: list[Path] = []
+    for rel in collect_base_markdown_files(docs_root, locale):
+        localized = docs_root / locale / rel
+        if not localized.is_file():
+            missing.append(rel)
+    return missing
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Check docs-site locale parity: every EN markdown page should have a localized counterpart."
+    )
+    parser.add_argument("--docs-root", default="docs-site")
+    parser.add_argument("--locale", default="zh-CN")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    repo_root = resolve_repo_root()
+    docs_root = Path(args.docs_root)
+    if not docs_root.is_absolute():
+        docs_root = repo_root / docs_root
+
+    if not docs_root.is_dir():
+        print(f"error: docs root does not exist: {docs_root}", file=sys.stderr)
+        return 2
+
+    missing = collect_missing_translations(docs_root, args.locale)
+
+    if args.json:
+        payload = {
+            "docs_root": str(docs_root),
+            "locale": args.locale,
+            "missing_count": len(missing),
+            "missing": [str(p).replace("\\", "/") for p in missing],
+        }
+        json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write("\n")
+    else:
+        if missing:
+            print(
+                f"i18n parity check failed for locale `{args.locale}`: {len(missing)} missing pages:"
+            )
+            for path in missing:
+                print(f"- {path.as_posix()}")
+        else:
+            print(f"i18n parity check passed for locale `{args.locale}`")
+
+    return 1 if missing else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/tests/test_check_i18n_parity.py b/scripts/tests/test_check_i18n_parity.py
diff --git a/scripts/tests/test_ci_workflows.py b/scripts/tests/test_ci_workflows.py
