refactor(paths): 本体根目录收敛到 locator.AGENTS_ROOT 单一持有者

28 号把本体根从 system/templates/ 搬到 system/agents/，agent-locator 就是为了当这个路径的唯一持有者而建的。但搬完之后仓库里仍有 13 处自己拼这个路径，等于 locator 只是多了一份副本、没有真正收敛： server/routes/company.js 9 处（6 个 TEMPLATES_DIR + 3 个 DATA_DIR，同一文件里只有 1 处用了 locator） server/services/task-service.js 1 处 server/src/core/skill-config-loader.js 1 处 server/src/core/devloop/loop-controller.js 1 处 scripts/extract-agent-prompts.js 1 处危害不是「不好看」，而是下一次再搬时改 12 处、漏 1 处：漏掉的那处指向一个不存在的目录，而本仓库读这类路径几乎都包在 fs.existsSync() 守卫里 —— 目录没了不报错，只是静默跳过。这个形状刚在 scripts/demo-harness-company.js 上实测过（base 本体没挂上，demo 跑出来的 agent 没有四段式骨架，脚本照常打印成功）。局部变量名保留不动（TEMPLATES_DIR / DATA_DIR / SYSTEM_AGENTS_DIR / agentsRoot / OUT_DIR），只把取值改成 locator.AGENTS_ROOT —— 名字是局部别名，无害；「路径这个事实」则收敛成一处，下次再搬只改 agent-locator.js。新增 server/tests/unit/agents-root-single-holder.test.js 锁住这条不变式：扫 server/ packages/ scripts/ 下所有源码，禁止 path.resolve/join 自己拼「以 ../ 开头、以 system/agents 结尾」的字面量。带「样本非空」前置断言，防止扫描路径写错时退化成永远通过。改坏一处实测能精确点名到文件行号。线索来自并行会话（它在准备改 company.js 时发现同一文件里 7 份定义）。实际比它看到的更多：它只查了 TEMPLATES_DIR，同文件另有 3 个 DATA_DIR、另外 3 个文件各 1 处。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

refactor(paths): 本体根目录收敛到 locator.AGENTS_ROOT 单一持有者
28 号把本体根从 system/templates/ 搬到 system/agents/，agent-locator 就是为了当这个路径的唯一持有者而建的。但搬完之后仓库里仍有 13 处自己拼这个路径，等于 locator 只是多了一份副本、没有真正收敛： server/routes/company.js 9 处（6 个 TEMPLATES_DIR + 3 个 DATA_DIR，同一文件里只有 1 处用了 locator） server/services/task-service.js 1 处 server/src/core/skill-config-loader.js 1 处 server/src/core/devloop/loop-controller.js 1 处 scripts/extract-agent-prompts.js 1 处危害不是「不好看」，而是下一次再搬时改 12 处、漏 1 处：漏掉的那处指向一个不存在的目录，而本仓库读这类路径几乎都包在 fs.existsSync() 守卫里 —— 目录没了不报错，只是静默跳过。这个形状刚在 scripts/demo-harness-company.js 上实测过（base 本体没挂上，demo 跑出来的 agent 没有四段式骨架，脚本照常打印成功）。局部变量名保留不动（TEMPLATES_DIR / DATA_DIR / SYSTEM_AGENTS_DIR / agentsRoot / OUT_DIR），只把取值改成 locator.AGENTS_ROOT —— 名字是局部别名，无害；「路径这个事实」则收敛成一处，下次再搬只改 agent-locator.js。新增 server/tests/unit/agents-root-single-holder.test.js 锁住这条不变式：扫 server/ packages/ scripts/ 下所有源码，禁止 path.resolve/join 自己拼「以 ../ 开头、以 system/agents 结尾」的字面量。带「样本非空」前置断言，防止扫描路径写错时退化成永远通过。改坏一处实测能精确点名到文件行号。线索来自并行会话（它在准备改 company.js 时发现同一文件里 7 份定义）。实际比它看到的更多：它只查了 TEMPLATES_DIR，同文件另有 3 个 DATA_DIR、另外 3 个文件各 1 处。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
yibo · 宜博
1 parent 367b4d50
Showing 6 changed files with 91 additions and 13 deletions
scripts/extract-agent-prompts.js
server/routes/company.js
server/services/task-service.js
server/src/core/devloop/loop-controller.js
server/src/core/skill-config-loader.js
server/tests/unit/agents-root-single-holder.test.js
@@ -21,7 +21,7 @@ const path = require(&#39;path&#39;);
 const ROLES = ['pm', 'architect', 'coder', 'tester', 'integrator', 'triager'];
 const SRC_DIR = path.resolve(__dirname, '../docs/prd/newfunction');
-const OUT_DIR = path.resolve(__dirname, '../system/agents');
+const OUT_DIR = require('../server/services/agent-locator').AGENTS_ROOT;
 function decodeHtmlEntities(s) {
   return s
@@ -133,7 +133,7 @@ router.patch(&#39;/templates/:templateId&#39;, (req, res) =&gt; {
     const path = require('path');
     const fs = require('fs');
-    const TEMPLATES_DIR = path.resolve(__dirname, '../../system/agents');
+    const TEMPLATES_DIR = locator.AGENTS_ROOT;
     const templateDir = path.join(TEMPLATES_DIR, templateId);
     if (!fs.existsSync(templateDir)) {
@@ -178,7 +178,7 @@ router.delete(&#39;/templates/:templateId&#39;, (req, res) =&gt; {
     const { templateId } = req.params;
     const path = require('path');
     const fs = require('fs');
-    const TEMPLATES_DIR = path.resolve(__dirname, '../../system/agents');
+    const TEMPLATES_DIR = locator.AGENTS_ROOT;
     const templateDir = path.join(TEMPLATES_DIR, templateId);
     if (!fs.existsSync(templateDir)) {
@@ -257,7 +257,7 @@ router.post(&#39;/templates/:templateId/generate&#39;, async (req, res) =&gt; {
     const path = require('path');
     const fs = require('fs');
     const config = require('../config');
-    const TEMPLATES_DIR = path.resolve(__dirname, '../../system/agents');
+    const TEMPLATES_DIR = locator.AGENTS_ROOT;
     const templateDir = path.join(TEMPLATES_DIR, templateId);
     if (!fs.existsSync(templateDir)) {
@@ -294,7 +294,7 @@ router.post(&#39;/templates/:templateId/train&#39;, async (req, res) =&gt; {
     const path = require('path');
     const fs = require('fs');
     const config = require('../config');
-    const TEMPLATES_DIR = path.resolve(__dirname, '../../system/agents');
+    const TEMPLATES_DIR = locator.AGENTS_ROOT;
     const templateDir = path.join(TEMPLATES_DIR, templateId);
     if (!fs.existsSync(templateDir)) {
@@ -356,7 +356,7 @@ router.post(&#39;/templates/:templateId/skills/upload&#39;, skillUpload.array(&#39;files&#39;, 5
   try {
     const { templateId } = req.params;
     const targetSubdir = req.body.targetDir || '.claude/skills';  // default to .claude/skills/ (Claude Code ACP reads from here)
-    const TEMPLATES_DIR = path.resolve(__dirname, '../../system/agents');
+    const TEMPLATES_DIR = locator.AGENTS_ROOT;
     const templateDir = path.join(TEMPLATES_DIR, templateId);
     if (!fs.existsSync(templateDir)) {
@@ -482,7 +482,7 @@ router.post(&#39;/templates/:templateId/provision&#39;, async (req, res) =&gt; {
     // 确定工作目录
     // 原来写的是 `../../data/system/templates` —— 一个从来不存在的路径（`data/` 多余），
     // 所以不带 agentDir 的调用一直是 404。顺手改正到合并后的本体目录。
-    const TEMPLATES_DIR = path.resolve(__dirname, '../../system/agents');
+    const TEMPLATES_DIR = locator.AGENTS_ROOT;
     let workDir;
     if (agentDir) {
       // 公司 agent 目录
@@ -595,7 +595,7 @@ router.get(&#39;/templates/:templateId/files&#39;, (req, res) =&gt; {
   try {
     const path = require('path');
     const fs = require('fs');
-    const DATA_DIR = path.resolve(__dirname, '../../system/agents');
+    const DATA_DIR = locator.AGENTS_ROOT;
     const templateDir = path.join(DATA_DIR, req.params.templateId);
     if (!fs.existsSync(templateDir)) {
@@ -651,7 +651,7 @@ router.get(&#39;/templates/:templateId/files/content&#39;, (req, res) =&gt; {
   try {
     const path = require('path');
     const fs = require('fs');
-    const DATA_DIR = path.resolve(__dirname, '../../system/agents');
+    const DATA_DIR = locator.AGENTS_ROOT;
     const filePath = req.query.path;
     if (!filePath) return res.status(400).json({ error: 'path 参数为必填' });
@@ -682,7 +682,7 @@ router.put(&#39;/templates/:templateId/files/content&#39;, (req, res) =&gt; {
   try {
     const path = require('path');
     const fs = require('fs');
-    const DATA_DIR = path.resolve(__dirname, '../../system/agents');
+    const DATA_DIR = locator.AGENTS_ROOT;
     const filePath = req.body.path;
     if (!filePath) return res.status(400).json({ error: 'path 参数为必填' });
@@ -3,7 +3,7 @@ const path = require(&#39;path&#39;);
 const locator = require('./agent-locator');
 const { listCompanyAgents } = require('./company-service');
-const SYSTEM_AGENTS_DIR = path.resolve(__dirname, '../../system/agents');
+const SYSTEM_AGENTS_DIR = require('./agent-locator').AGENTS_ROOT;
 const TASK_META_DIR = path.resolve(__dirname, '../../system/tasklog');
 /**
@@ -35,7 +35,7 @@ unitRegistry.attachSseBroker(sseBroker);
 bugTracker.attachSseBroker(sseBroker);
 bugTracker.attachTimelineLogger(timelineLogger);
-const TEMPLATES_DIR = path.resolve(__dirname, '../../../../system/agents');
+const TEMPLATES_DIR = require('../../../services/agent-locator').AGENTS_ROOT;
 /**
  * 新建项目:
@@ -23,7 +23,7 @@ const path = require(&#39;path&#39;);
 function loadConfigFromSkills(skillsCodeDir, backendsConfig = {}) {
     // 扫描所有 Agent 专属的技能挂载目录 (符合 Local File-System First)
     const dirsToScan = [];
-    const agentsRoot = path.resolve(__dirname, '../../../system/agents');
+    const agentsRoot = require('../../services/agent-locator').AGENTS_ROOT;
     if (fs.existsSync(agentsRoot)) {
         const agentFolders = fs.readdirSync(agentsRoot, { withFileTypes: true });
         for (const f of agentFolders) {
+/**
+ * 「本体根目录」这个事实只能有一个持有者：`agent-locator.AGENTS_ROOT`。
+ *
+ * 为什么需要这条元测试（28 号改造的直接教训）：
+ * 28 号把本体根从 `system/templates/` 搬到 `system/agents/`，搬之前这个路径在
+ * 5 个文件里被硬编码了 12 份（`server/routes/company.js` 一个文件里就有 9 份 ——
+ * 6 个 `TEMPLATES_DIR` + 3 个 `DATA_DIR`，只有 1 处用了权威访问器）。
+ *
+ * 12 份副本的危害不是「不好看」，而是**下一次再搬时改 11 处、漏 1 处**：
+ * 漏掉的那处会指向一个不存在的目录，而本仓库读这类路径几乎都包在
+ * `fs.existsSync()` 守卫里 —— 目录没了不报错，只是静默跳过（并行会话在
+ * `scripts/demo-harness-company.js` 实测过这个形状：base 本体没挂上，
+ * demo 跑出来的 agent 没有四段式骨架，脚本照常打印成功）。
+ *
+ * 同一个病在本仓库已有多个实例：`canDispatch` 的取值域被前端复述过一份、
+ * `ACTIVE_ROOT_RUN_STATUS` 在两个文件里逐字重复、`isUngraduatedStatus()` 的取值域
+ * 一度按「≠ active 就挡」判而误伤 36 个本体。**同一个事实只能有一处持有者 —— 路径也是事实。**
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+
+/** 只扫真正会被执行的源码，跳过依赖、构建产物、测试自身与 locator 本身 */
+const SCAN_DIRS = ['server', 'packages', 'scripts'];
+const SKIP_DIR = /(^|\/)(node_modules|dist|\.git|coverage)(\/|$)/;
+const SKIP_FILE = /\.test\.js$|agent-locator\.js$/;
+
+/**
+ * 「拼出本体根目录」的形状：path.resolve/join 里出现以 ../ 开头、以 system/agents 结尾的字面量。
+ * 只认路径构造，不认注释里提到的字符串 —— 注释里写 `system/agents/` 是正常的文档行为。
+ */
+const HARDCODED = /path\.(?:resolve|join)\([^)]*['"`][^'"`]*\.\.\/[^'"`]*system\/agents['"`]/;
+
+function walk(dir, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // 目录不存在（如仓库裁剪过）就跳过，不让本测试成为噪声源
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (SKIP_DIR.test(full)) continue;
+    if (e.isDirectory()) walk(full, out);
+    else if (e.name.endsWith('.js') && !SKIP_FILE.test(e.name)) out.push(full);
+  }
+  return out;
+}
+
+describe('本体根目录只有一个持有者（28 §5.1）', () => {
+  const files = SCAN_DIRS.flatMap((d) => walk(path.join(REPO_ROOT, d)));
+
+  it('扫描样本非空 —— 防止路径写错时本测试退化成永远通过', () => {
+    // 没有这一条，上面 walk() 的容错会让「一个文件都没扫到」表现为全绿。
+    expect(files.length).toBeGreaterThan(100);
+  });
+
+  it('没有任何文件自己拼 system/agents 根路径（一律走 locator.AGENTS_ROOT）', () => {
+    const offenders = [];
+    for (const f of files) {
+      const src = fs.readFileSync(f, 'utf-8');
+      src.split('\n').forEach((line, i) => {
+        if (HARDCODED.test(line)) {
+          offenders.push(`${path.relative(REPO_ROOT, f)}:${i + 1} → ${line.trim()}`);
+        }
+      });
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('locator.AGENTS_ROOT 指向真实存在的目录', () => {
+    const { AGENTS_ROOT } = require('../../services/agent-locator');
+    expect(fs.existsSync(AGENTS_ROOT)).toBe(true);
+    expect(path.basename(AGENTS_ROOT)).toBe('agents');
+  });
+});