From 20a58e83bea4e4807885c1116a0a6d212c04995c Mon Sep 17 00:00:00 2001 From: DeliciousBuding Date: Thu, 3 Sep 2026 22:17:04 +0800 Subject: [PATCH] =?UTF-8?q?chore(repo):=20=E6=B6=88=E8=9E=8D=20reference/?= =?UTF-8?q?=20=E7=AC=AC=E4=B8=89=E6=96=B9=E7=A0=94=E7=A9=B6=E5=89=AF?= =?UTF-8?q?=E6=9C=AC=E6=9C=BA=E5=88=B6=E2=80=94=E2=80=94=E8=AF=A5=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E5=8F=AA=E5=89=A9=E4=B8=80=E4=BB=BD=E8=87=AA=E7=A7=B0?= =?UTF-8?q?"=E5=B7=B2=E6=B8=85=E7=90=86=E6=97=A0=E6=B4=BB=E8=B7=83=20check?= =?UTF-8?q?out"=E7=9A=84=20INDEX.md=20=E5=A2=93=E7=A2=91=EF=BC=8C=E5=94=AF?= =?UTF-8?q?=E4=B8=80=E7=94=9F=E4=BA=A7=E8=80=85=20sync-reference.py?= =?UTF-8?q?=EF=BC=88clone=2026=20=E4=B8=AA=E7=AC=AC=E4=B8=89=E6=96=B9?= =?UTF-8?q?=E4=BB=93=EF=BC=89=E5=9C=A8=20CI/Makefile/docs=20=E9=9B=B6?= =?UTF-8?q?=E8=B0=83=E7=94=A8=E8=80=85=EF=BC=8C=E8=80=8C=20verify-doc-ssot?= =?UTF-8?q?=20=E5=8D=B4=E7=94=A8=203=20=E5=A4=84=E8=87=AA=E6=8C=87?= =?UTF-8?q?=EF=BC=88is=5Factive=5Fdoc=E3=80=81=E9=95=9C=E5=83=8F=E5=AF=B9?= =?UTF-8?q?=E3=80=8180=20=E8=A1=8C=E9=A2=84=E7=AE=97=EF=BC=89=E7=BB=B4?= =?UTF-8?q?=E6=8C=81=E5=AE=83=E5=AD=98=E5=9C=A8=EF=BC=9B=E5=88=A0=E5=A2=93?= =?UTF-8?q?=E7=A2=91=20+=20=E5=88=A0=E8=84=9A=E6=9C=AC=20+=20=E5=88=A0=20s?= =?UTF-8?q?etup.py=20=E7=9A=84=20-Reference/--reference-core/--reference-a?= =?UTF-8?q?ll=20=E4=B8=89=E4=B8=AA=E6=AD=BB=E5=BC=80=E5=85=B3=EF=BC=88?= =?UTF-8?q?=E8=B4=9F=E8=AF=81=EF=BC=9A--reference-core=20=E7=8E=B0=20rc=3D?= =?UTF-8?q?2=EF=BC=89+=20=E5=88=A0=20AGENTS.md=20=E5=8F=AA=E5=89=A9=201=20?= =?UTF-8?q?=E8=A1=8C=E7=9A=84=E3=80=90=E5=8F=82=E8=80=83=E3=80=91=E5=88=86?= =?UTF-8?q?=E7=B1=BB=20+=20=E5=88=A0=20.gitignore/.dockerignore=20?= =?UTF-8?q?=E7=9A=84=20reference=20=E6=AD=BB=E9=85=8D=E7=BD=AE=20+=20?= =?UTF-8?q?=E5=88=A0=204=20=E5=A4=84=E6=8C=87=E5=90=91=E5=B7=B2=E5=A4=96?= =?UTF-8?q?=E8=BF=81=20docs/reference/cross-comparison=20=E7=9A=84=20Go=20?= =?UTF-8?q?=E6=AD=BB=E6=8C=87=E9=92=88=E6=B3=A8=E9=87=8A=EF=BC=8812=20?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=87=80=20-137=20=E8=A1=8C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 证据：verify-doc-ssot rc=0（AGENTS.md 98 路径 / verifier-map 68 脚本 / 29 自测全绿）；verify-doc-entrypoints.Tests rc=0；go build ./... rc=0 + go vet 4 个被改包 rc=0；残留引用扫描 reference/INDEX、sync-reference、cross-comparison、reference-core/-all 全 0 命中。 Co-authored-by: Cursor --- .dockerignore | 3 - .gitignore | 3 - AGENTS.md | 3 +- edge-server/internal/adapters/hooks.go | 1 - edge-server/internal/agents/registry.go | 1 - .../lifecycle/process_executor_structured.go | 1 - .../internal/orchestration/contracts.go | 1 - reference/INDEX.md | 19 ---- scripts/dev/setup.py | 21 +---- scripts/dev/setup.sh | 4 +- scripts/dev/sync-reference.py | 88 ------------------- scripts/verify/verify-doc-ssot.py | 4 +- 12 files changed, 6 insertions(+), 143 deletions(-) delete mode 100644 reference/INDEX.md delete mode 100644 scripts/dev/sync-reference.py diff --git a/.dockerignore b/.dockerignore index 9d6b523e8..05f81335d 100644 --- a/.dockerignore +++ b/.dockerignore @@ -85,9 +85,6 @@ app/web/pnpm-lock.yaml # ── Rust / Tauri (not needed for Go build) ──── target/ -# ── Reference repos ─────────────────────────── -reference/ - # ── Local ops state ─────────────────────────── .ops .tmp diff --git a/.gitignore b/.gitignore index 2e5fce3e1..896519d95 100644 --- a/.gitignore +++ b/.gitignore @@ -266,9 +266,6 @@ docs/deployment/region-*.md docs/deployment/*-deployment-runbook.md docs/deployment/*deployment* -# Cloned reference repos (at repo root only) -/reference/* -!/reference/INDEX.md /chat-verify/ # ============================================================================= diff --git a/AGENTS.md b/AGENTS.md index 16562dd20..9d0e3146f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ ## 0.5 根级目录地图 -【活】= 维护中的源码/文档；【产物】= 构建/临时产物（gitignored，勿提交）；【参考】= 只读副本。 +【活】= 维护中的源码/文档；【产物】= 构建/临时产物（gitignored，勿提交）。 | 目录 | 分类 | 职责 | |---|---|---| @@ -28,7 +28,6 @@ | `hub-server/` | 活 | Go Hub 服务（REST/WS/OIDC/dispatch/agentteam） | | node_modules/ | 产物 | 依赖（gitignored） | | `pkg/` | 活 | Go 共享包（errcode 等） | -| `reference/` | 参考 | 第三方源码只读副本（gitignored，INDEX.md 管理） | | `scripts/` | 活 | 验证/开发/发布脚本（verify/dev/e2e/git-hooks/lib/release/smoke/） | | `tests/` | 活 | 跨服务测试 | diff --git a/edge-server/internal/adapters/hooks.go b/edge-server/internal/adapters/hooks.go index ac091b0f2..d3a2f3ba7 100644 --- a/edge-server/internal/adapters/hooks.go +++ b/edge-server/internal/adapters/hooks.go @@ -1,6 +1,5 @@ // Package adapters — AgentHook 接口定义 // 基于 Claude Code (28 hooks) + OpenCode (19 hooks) 收敛为 6 核心 hooks -// 参考: docs/reference/02-cross-comparison/00-synthesis.md §2.2 package adapters diff --git a/edge-server/internal/agents/registry.go b/edge-server/internal/agents/registry.go index 1bf6a9ec4..050a58b42 100644 --- a/edge-server/internal/agents/registry.go +++ b/edge-server/internal/agents/registry.go @@ -2,7 +2,6 @@ // for the AgentHub Orchestrator. It tracks runtime agent instances, their // status, and enables communication between orchestrator and sub-agents. // -// Reference: docs/reference/cross-comparison/03-orchestration.md Layer 2 // Reference: historical codex-cli AgentTree pattern indexed by docs/history.md. // // Residual pure-helper peel #1154: Registry core API stays here; types, diff --git a/edge-server/internal/lifecycle/process_executor_structured.go b/edge-server/internal/lifecycle/process_executor_structured.go index b96580434..58ed70c2f 100644 --- a/edge-server/internal/lifecycle/process_executor_structured.go +++ b/edge-server/internal/lifecycle/process_executor_structured.go @@ -87,5 +87,4 @@ func (e *ProcessExecutor) publishStructuredOutput(wg *sync.WaitGroup, run store. // sessions.create({parentID}) pattern where sub-agents get independent sessions // with derived permissions and no shared context contamination. // -// Reference: docs/reference/cross-comparison/03-orchestration.md Layer 3 (Supervisor routing). // Reference: OpenCode task.ts:145-162 (sessions.create with parentID, deriveSubagentSessionPermission). diff --git a/edge-server/internal/orchestration/contracts.go b/edge-server/internal/orchestration/contracts.go index b6ee46b08..a236d67c5 100644 --- a/edge-server/internal/orchestration/contracts.go +++ b/edge-server/internal/orchestration/contracts.go @@ -87,7 +87,6 @@ type AgentCapabilities struct { } // SubAgentTask describes a sub-agent task to be dispatched by the orchestrator. -// Reference: docs/reference/cross-comparison/03-orchestration.md Layer 3 (Supervisor routing). type SubAgentTask struct { TaskID string `json:"taskId"` Description string `json:"description"` diff --git a/reference/INDEX.md b/reference/INDEX.md deleted file mode 100644 index fe8ec19ff..000000000 --- a/reference/INDEX.md +++ /dev/null @@ -1,19 +0,0 @@ -# Reference Workspace Index - -最后更新：2026-08-09 - -`reference/` 已清理，当前无活跃 checkout。本地第三方源码树曾用于研究对照，已不在仓库内维护，亦不构成 AgentHub 产品架构真相。 - -## 恢复引用 - -如需恢复历史 checkout 用于研究，使用同步脚本： - -```bash -python scripts/dev/sync-reference.py --Tier all -``` - -恢复后请勿将 reference 结论写入本索引；研究结论应沉淀到归属活文档（`docs/architecture.md`、`api/` 或 `AGENTS.md`），长篇研究笔记通过 `docs/history.md` 归档。 - -## 索引 - -历史第三方源码报告与快照见外部归档，指针在 [../docs/history.md](../docs/history.md)。当前研究入口（若有）见 [../docs/reference/README.md](../docs/reference/README.md)。 diff --git a/scripts/dev/setup.py b/scripts/dev/setup.py index 72ae283a7..0fd776ad7 100644 --- a/scripts/dev/setup.py +++ b/scripts/dev/setup.py @@ -1,10 +1,9 @@ #!/usr/bin/env python3 """setup — AgentHub 本地环境配置（ps1 迁移，契约见 server docs/design/ps1-to-python-migration.md）。 -启用 git hooks（scripts/git-hooks），可选同步 public reference 仓库 -（-Reference core|all；兼容原 setup.sh 的 --reference-core / --reference-all）。 +启用 git hooks（scripts/git-hooks）。 -契约：stdlib only；参数/输出行（`Git hooks enabled: scripts/git-hooks` / +契约：stdlib only；输出行（`Git hooks enabled: scripts/git-hooks` / `Setup complete.`）与 ps1 一致；退出码 0=通过。 """ @@ -19,16 +18,7 @@ def main() -> int: parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("--Reference", "-Reference", default="none", choices=["none", "core", "all"]) - parser.add_argument("--reference-core", action="store_true", help="sync core reference repos (setup.sh compatibility)") - parser.add_argument("--reference-all", action="store_true", help="sync all reference repos (setup.sh compatibility)") - args = parser.parse_args() - - reference = args.Reference - if args.reference_core: - reference = "core" - if args.reference_all: - reference = "all" + parser.parse_args() repo_root = os.path.realpath(REPO_ROOT) os.chdir(repo_root) @@ -38,11 +28,6 @@ def main() -> int: raise RuntimeError(f"git config core.hooksPath failed with exit code {run.returncode}") print("Git hooks enabled: scripts/git-hooks") - if reference != "none": - sync_run = subprocess.run([sys.executable, os.path.join(SCRIPT_DIR, "sync-reference.py"), "--Tier", reference]) - if sync_run.returncode != 0: - return sync_run.returncode - print("Setup complete.") return 0 diff --git a/scripts/dev/setup.sh b/scripts/dev/setup.sh index b0de96a17..686ff66b4 100755 --- a/scripts/dev/setup.sh +++ b/scripts/dev/setup.sh @@ -2,9 +2,7 @@ # ─────────────────────────────────────────────── # AgentHub 本地环境配置（Python 实现，原 ps1 已迁移；本文件是兼容 launcher） # 用法: -# ./scripts/dev/setup.sh # 仅启用 git hooks -# ./scripts/dev/setup.sh --reference-core # 同步 core reference 仓库 -# ./scripts/dev/setup.sh --reference-all # 同步全部 reference 仓库 +# ./scripts/dev/setup.sh # 启用 git hooks # ─────────────────────────────────────────────── set -euo pipefail diff --git a/scripts/dev/sync-reference.py b/scripts/dev/sync-reference.py deleted file mode 100644 index accd4f768..000000000 --- a/scripts/dev/sync-reference.py +++ /dev/null @@ -1,88 +0,0 @@ -#!/usr/bin/env python3 -"""sync-reference — 克隆或更新 public reference 仓库（ps1 迁移，契约见 server docs/design/ps1-to-python-migration.md）。 - -reference 仓库被 git 忽略；只有 reference/INDEX.md 被跟踪。core tier 6 个 -仓库，all tier 全部。已存在 .git 的仓库执行 pull --ff-only，存在但非 git -仓库的跳过并告警，其余 clone --depth 1。 - -契约：stdlib only；参数（-Tier core|all）/输出行（`Updating reference/` / -`Cloning reference/` / `Skipping reference/: directory exists but -is not a git repository` / `Reference sync complete. See reference/INDEX.md -for the full reading map.`）与 ps1 一致；退出码 0=通过。 -""" - -import argparse -import os -import subprocess -import sys - -SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__)) -REPO_ROOT = os.path.dirname(os.path.dirname(SCRIPT_DIR)) - -REPOS = [ - {"Tier": "core", "Name": "multica", "Url": "https://github.com/multica-ai/multica.git"}, - {"Tier": "core", "Name": "codex", "Url": "https://github.com/openai/codex.git"}, - {"Tier": "core", "Name": "opencode", "Url": "https://github.com/anomalyco/opencode.git"}, - {"Tier": "core", "Name": "OpenHands", "Url": "https://github.com/All-Hands-AI/OpenHands.git"}, - {"Tier": "core", "Name": "claudecodeui", "Url": "https://github.com/siteboon/claudecodeui.git"}, - {"Tier": "core", "Name": "opcode", "Url": "https://github.com/winfunc/opcode.git"}, - {"Tier": "all", "Name": "aider", "Url": "https://github.com/Aider-AI/aider.git"}, - {"Tier": "all", "Name": "ChatDev", "Url": "https://github.com/OpenBMB/ChatDev.git"}, - {"Tier": "all", "Name": "claude-code-viewer", "Url": "https://github.com/d-kimuson/claude-code-viewer.git"}, - {"Tier": "all", "Name": "claude-code-webui", "Url": "https://github.com/sugyan/claude-code-webui.git"}, - {"Tier": "all", "Name": "cline", "Url": "https://github.com/cline/cline.git"}, - {"Tier": "all", "Name": "continue", "Url": "https://github.com/continuedev/continue.git"}, - {"Tier": "all", "Name": "crush", "Url": "https://github.com/charmbracelet/crush.git"}, - {"Tier": "all", "Name": "dify", "Url": "https://github.com/langgenius/dify.git"}, - {"Tier": "all", "Name": "eca", "Url": "https://github.com/editor-code-assistant/eca.git"}, - {"Tier": "all", "Name": "emdash", "Url": "https://github.com/generalaction/emdash.git"}, - {"Tier": "all", "Name": "Flowise", "Url": "https://github.com/FlowiseAI/Flowise.git"}, - {"Tier": "all", "Name": "goose", "Url": "https://github.com/aaif-goose/goose.git"}, - {"Tier": "all", "Name": "jean", "Url": "https://github.com/coollabsio/jean.git"}, - {"Tier": "all", "Name": "kanna", "Url": "https://github.com/jakemor/kanna.git"}, - {"Tier": "all", "Name": "langflow", "Url": "https://github.com/langflow-ai/langflow.git"}, - {"Tier": "all", "Name": "LibreChat", "Url": "https://github.com/danny-avila/LibreChat.git"}, - {"Tier": "all", "Name": "orca", "Url": "https://github.com/stablyai/orca.git"}, - {"Tier": "all", "Name": "picoclaw", "Url": "https://github.com/sipeed/picoclaw.git"}, - {"Tier": "all", "Name": "Roo-Code", "Url": "https://github.com/RooCodeInc/Roo-Code.git"}, - {"Tier": "all", "Name": "ruflo", "Url": "https://github.com/ruvnet/ruflo.git"}, -] - - -def main() -> int: - parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("--Tier", "-Tier", default="core", choices=["core", "all"]) - args = parser.parse_args() - - repo_root = os.path.realpath(REPO_ROOT) - reference_root = os.path.join(repo_root, "reference") - - selected = [repo for repo in REPOS if args.Tier == "all" or repo["Tier"] == "core"] - - os.makedirs(reference_root, exist_ok=True) - - for repo in selected: - target = os.path.join(reference_root, repo["Name"]) - if os.path.isdir(os.path.join(target, ".git")): - print(f"Updating reference/{repo['Name']}") - run = subprocess.run(["git", "-C", target, "pull", "--ff-only"]) - if run.returncode != 0: - raise RuntimeError(f"git pull failed for reference/{repo['Name']} with exit code {run.returncode}") - elif os.path.exists(target): - print(f"WARNING: Skipping reference/{repo['Name']}: directory exists but is not a git repository") - else: - print(f"Cloning reference/{repo['Name']}") - run = subprocess.run(["git", "clone", "--depth", "1", repo["Url"], target]) - if run.returncode != 0: - raise RuntimeError(f"git clone failed for reference/{repo['Name']} with exit code {run.returncode}") - - print("Reference sync complete. See reference/INDEX.md for the full reading map.") - return 0 - - -if __name__ == "__main__": - try: - sys.exit(main()) - except Exception as exc: # noqa: BLE001 —— 顶层兜底，对齐 ps1 $ErrorActionPreference='Stop'，禁止静默吞错 - print(f"ERROR: {exc}", file=sys.stderr) - sys.exit(1) diff --git a/scripts/verify/verify-doc-ssot.py b/scripts/verify/verify-doc-ssot.py index 7ade668bd..d6cb609ca 100644 --- a/scripts/verify/verify-doc-ssot.py +++ b/scripts/verify/verify-doc-ssot.py @@ -46,7 +46,7 @@ def is_active_doc(path: str) -> bool: p = normalize_path(path) if re.match(r"^docs/(archive|archives|audit|release)/", p): return False - if p in ("AGENTS.md", "CONTRIBUTING.md", "reference/INDEX.md", "README.md", "README_EN.md"): + if p in ("AGENTS.md", "CONTRIBUTING.md", "README.md", "README_EN.md"): return True if p in ("api/README.md", "api/events.md", "api/conventions.md"): return True @@ -175,7 +175,6 @@ def check_required_markers() -> None: ("hub-server/README.md", "Source Map"), ("hub-server/deployments/README.md", "Live host"), ("hub-server/tests/README.md", "Integration Tests"), - ("reference/INDEX.md", "docs/reference/README.md"), ("CONTRIBUTING.md", "旧详细贡献指南见"), ("docs/governance/README.md", "Login fixture topology gate"), ("docs/governance/README.md", "已迁移至私有文档中枢"), @@ -263,7 +262,6 @@ def check_max_lines() -> None: "AGENTS.md": 300, "CHANGELOG.md": 90, "CONTRIBUTING.md": 90, - "reference/INDEX.md": 80, "api/README.md": 100, "api/events.md": 180, "api/conventions.md": 190,