@furongjun1999/dsh-memory 0.4.11 → 0.5.0

package/src/tools.ts

@@ -1,212 +1,212 @@
-/**
- * 工具桥接：运行时从灵枢拉取工具清单（tools/list），把 JSON Schema
- * 转换为 dsh-tools 的 ParameterSchemaSpec，经 defineTool 注册进 ctx.tools。
- *
- * 动态拉取意味着灵枢库升级新增工具后，DSH 侧零改动即可获得新能力。
- */
-
-import type { Context } from '@deepseek-ai/cordis'
-import { defineTool, type ParameterPropertySpec, type ParameterSchemaSpec, type ValueSchemaSpec } from '@deepseek-ai/dsh-tools'
-import type { LingshuBridge, McpTool } from './bridge.ts'
-
-/** 默认暴露的核心工具集合：**记忆面已基元化**，只注册 `cg` / `stg` 两个认知基元。
- *
- * 三层拆分 S4 收敛后，插件工具面真源是 `md_cg.mcp_server`（不再是 pip aeis）；
- * 旧的 aeis 工具名（remember/recall/think…）已不存在，写在这里只会被筛成空集
- * ——「工具永久缺失」的根因，故一并移除。全部记忆/召回/时间线/落图能力由
- * `cg(op=…)` / `stg(op=…)` 覆盖（见 src/lib/mdcg_client.ts 的显式映射）。 */
-export const CORE_TOOLS = [
-  'cg',   // md_cg 认知图统一入口（op 分发：route/read/recent/identity/verify/whitebox…）
-  'stg',  // md_cg 时空图入口（timeline/relation/anchor/consistency…）
-] as const
-
-/**
- * 大脑模式工具集：`cg`/`stg` 基元 + md_cg 全部细粒度工具（`MDCG_MCP_SURFACE=full`）。
- *
- * 即「完整认知面」。不再区分身体/视觉——那些工具随 aeis 剥离，主仓无对应物。
- * 管理类（forget / restore / review_decide）按映射表裁定「收窄后不留」，不在此列
- * （如需显式启用，用 `tools: ['mdcg_forget', …]` 显式数组——显式配置不受 RISK 限制）。
- */
-export const BRAIN_TOOLS = [
-  'cg', 'stg',
-  // 记忆读写
-  'mdcg_remember', 'mdcg_recall', 'mdcg_search', 'mdcg_get',
-  // 反思 / 验证 / 飞轮 / 负记忆
-  'mdcg_reflect', 'mdcg_verify', 'mdcg_flywheel', 'mdcg_mine_fix_pairs',
-  'mdcg_rejected', 'mdcg_unresolved',
-  // 审核队列（入队 / 列队 / 记录审计；裁决 review_decide 属管理类，不在此列）
-  'mdcg_propose', 'mdcg_review_list', 'mdcg_review_records',
-  // 保护 / 遗忘留痕（forget 属管理类，不在此列）
-  'mdcg_protect', 'mdcg_forgetting_history',
-  // 身份 / 一致性 / 元认知 / 自我状态
-  'mdcg_identity', 'mdcg_consistency', 'mdcg_metacognition', 'mdcg_self_state',
-  // 预测 / 因果 / 演化账本
-  'mdcg_predict', 'mdcg_causal', 'mdcg_evolution',
-  // 服务 / 状态
-  'mdcg_health', 'mdcg_whoami', 'mdcg_ingest', 'mdcg_watermarks',
-  'mdcg_whitebox', 'mdcg_service_info',
-] as const
-
-/** tools 配置：'core' | 'brain' | 'all' | 显式名称数组。 */
-export type ToolSelection = 'core' | 'brain' | 'all' | string[]
-
-/** P1 修复（GPT 审查）：只读/无副作用工具才允许并发——写操作（记忆/关系/
- * 生命周期/摄取/学习）标 false，防止 DSH 并行调用导致 SQLite 写入竞争、
- * 状态顺序错乱、关系边重复等。 */
-const READ_TOOLS = new Set([
-  // —— md_cg 细粒度只读工具（非多态：无 action 写分支）——
-  'mdcg_recall', 'mdcg_search', 'mdcg_get', 'mdcg_review_list', 'mdcg_review_records',
-  'mdcg_forgetting_history', 'mdcg_health', 'mdcg_whoami', 'mdcg_watermarks', 'mdcg_service_info',
-  // 注：cg / stg 是多态基元（op=focus/route 只读，op=write 写），一律按写处理（串行）。
-  // 多态工具（mdcg_predict/causal/evolution/protect/identity/self_state/whitebox…）
-  // 含 action=写 分支，同样保守按写处理。
-])
-
-/** 按工具名判定并发安全（只读查询 true；写操作 false） */
-export function isToolConcurrencySafe(name: string): boolean {
-  return READ_TOOLS.has(name)
-}
-
-/**
- * P1 完善（GPT 审查·tools:all 自动扩权）：即使 selection='all' 也排除的宿主级
- * 风险工具——此前后端新增工具即自动暴露给 Agent（动态扩权无 denylist）。
- * 排除原则：宿主命令执行/权限终裁/外部设备/自主生命周期控制/角色卡写入。
- * 显式名称数组（显式配置）不受此名单限制（配置者已明确选择）。
- */
-export const RISK_TOOLS = new Set([
-  // —— md_cg 管理类（映射表裁定「收窄后不留」，需 can_admin）：即使 tools:'all'
-  //    也不自动暴露；要启用须用显式名称数组 ——
-  'mdcg_forget',        // 软删除（管理隔离：需 can_admin）
-  'mdcg_restore',       // 强恢复校验（管理隔离：需 can_admin）
-  'mdcg_review_decide', // 审核终裁（管理隔离：需 can_admin，等效设计者裁决）
-])
-
-/** 按配置筛选工具名（'all' 时排除 RISK_TOOLS 宿主级危险工具）。 */
-export function selectTools(all: string[], selection: ToolSelection): string[] {
-  if (selection === 'all') return all.filter((name) => !RISK_TOOLS.has(name))
-  const allowed = new Set(
-    selection === 'core' ? CORE_TOOLS
-      : selection === 'brain' ? BRAIN_TOOLS
-      : selection,
-  )
-  return all.filter((name) => allowed.has(name))
-}
-
-/** 把 MCP JSON Schema 的属性表转换为 ParameterSchemaSpec。 */
-export function schemaToParameters(inputSchema: Record<string, unknown> | undefined): ParameterSchemaSpec {
-  if (!inputSchema || typeof inputSchema !== 'object') return {}
-  const properties = inputSchema['properties'] as Record<string, unknown> | undefined
-  if (!properties || typeof properties !== 'object') return {}
-  const required = new Set(Array.isArray(inputSchema['required']) ? (inputSchema['required'] as string[]) : [])
-  const spec: Record<string, ParameterPropertySpec> = {}
-  for (const [key, raw] of Object.entries(properties)) {
-    const value = toValueSpec(raw)
-    if (required.has(key)) {
-      spec[key] = { ...value, required: true as const }
-    } else {
-      spec[key] = value
-    }
-  }
-  return spec
-}
-
-/** 递归转换单个 JSON Schema 节点为 ValueSchemaSpec。 */
-function toValueSpec(raw: unknown): ValueSchemaSpec {
-  if (typeof raw !== 'object' || raw === null) return { type: 'json' }
-  const node = raw as Record<string, unknown>
-  const annotations: { description?: string } = {}
-  if (typeof node['description'] === 'string') annotations.description = node['description'] as string
-  const type = node['type']
-  const enumValues = Array.isArray(node['enum']) ? (node['enum'] as unknown[]) : undefined
-  switch (type) {
-    case 'string':
-      return { type: 'string', ...annotations, ...(enumValues ? { enum: enumValues as string[] } : {}) }
-    case 'number':
-      return { type: 'number', ...annotations }
-    case 'integer':
-      return { type: 'integer', ...annotations }
-    case 'boolean':
-      return { type: 'boolean', ...annotations }
-    case 'null':
-      return { type: 'null', ...annotations }
-    case 'array': {
-      const spec: { type: 'array'; items?: ValueSchemaSpec } & typeof annotations = { type: 'array', ...annotations }
-      if (node['items'] !== undefined) spec.items = toValueSpec(node['items'])
-      return spec
-    }
-    case 'object': {
-      const props = schemaToParameters(node)
-      // P1 修复（GPT 审查）：尊重后端 additionalProperties 声明（false 保留），
-      // 不再无条件 true——此前后端写 false 也会被覆盖成 true，DSH 侧认为
-      // 参数合法但后端拒绝。
-      const additional = node['additionalProperties'] === false ? false : true
-      return { type: 'object', properties: props, additionalProperties: additional, ...annotations }
-    }
-    default:
-      return { type: 'json', ...annotations }
-  }
-}
-
-/** 从灵枢 content 数组中提取文本（MCP text block 拼接）。 */
-export function extractText(content: Array<{ type: string; text?: string; [key: string]: unknown }>): string {
-  return content
-    .map((block) => (block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
-    .filter(Boolean)
-    .join('\n')
-}
-
-/** 注册灵枢工具到 ctx.tools；返回取消注册函数。 */
-export async function registerLingshuTools(
-  ctx: Context,
-  bridge: LingshuBridge,
-  opts: { selection: ToolSelection; toolPrefix: string },
-): Promise<() => void> {
-  const tools = await bridge.listTools()
-  const wanted = new Set(selectTools(tools.map((t) => t.name), opts.selection))
-  const disposers: Array<() => void> = []
-  const registered: string[] = []
-  try {
-    for (const tool of tools) {
-      if (!wanted.has(tool.name)) continue
-      const publicName = `${opts.toolPrefix}${tool.name}`
-      const definition = defineTool({
-        name: publicName,
-        description: tool.description || `灵枢 ${tool.name}`,
-        parameters: schemaToParameters(tool.inputSchema),
-        output: {
-          schema: { type: 'json' } as never,
-          render(_args, value) {
-            return [{ type: 'text', text: extractText((value as McpCallResultLike).content ?? []) }]
-          },
-        },
-        timeoutMs: 120_000,
-        // P1 修复（GPT 审查）：按工具分类——只读查询可并发，写操作串行
-        isConcurrencySafe: () => isToolConcurrencySafe(tool.name),
-        // P1 修复（GPT 审查）：接收 exec.signal（用户取消/上层超时）——
-        // 此前完全忽略取消，取消后写操作（remember/relate/ingest 等）仍可能产生副作用
-        async execute(args: Record<string, unknown>, exec: { signal: AbortSignal }) {
-          if (exec.signal.aborted) throw new Error(`灵枢 ${tool.name} 已取消`)
-          const result = await bridge.callTool(tool.name, args as Record<string, unknown>, exec.signal)
-          if (exec.signal.aborted) throw new Error(`灵枢 ${tool.name} 已取消`)
-          if (result.isError) {
-            throw new Error(extractText(result.content) || `灵枢 ${tool.name} 执行失败`)
-          }
-          return { content: result.content } as never
-        },
-      })
-      disposers.push(ctx.tools.register(definition))
-      registered.push(publicName)
-    }
-  } catch (err) {
-    for (const dispose of disposers) dispose()
-    throw err
-  }
-  ctx.logger.info(`dsh-memory: 已注册 ${registered.length} 个灵枢工具（${registered.join(', ')}）`)
-  return () => {
-    for (const dispose of disposers) dispose()
-  }
-}
-
-interface McpCallResultLike {
-  content: Array<{ type: string; text?: string; [key: string]: unknown }>
-}
+/**
+ * 工具桥接：运行时从灵枢拉取工具清单（tools/list），把 JSON Schema
+ * 转换为 dsh-tools 的 ParameterSchemaSpec，经 defineTool 注册进 ctx.tools。
+ *
+ * 动态拉取意味着灵枢库升级新增工具后，DSH 侧零改动即可获得新能力。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool, type ParameterPropertySpec, type ParameterSchemaSpec, type ValueSchemaSpec } from '@deepseek-ai/dsh-tools'
+import type { LingshuBridge, McpTool } from './bridge.ts'
+
+/** 默认暴露的核心工具集合：**记忆面已基元化**，只注册 `cg` / `stg` 两个认知基元。
+ *
+ * 三层拆分 S4 收敛后，插件工具面真源是 `md_cg.mcp_server`（不再是 pip aeis）；
+ * 旧的 aeis 工具名（remember/recall/think…）已不存在，写在这里只会被筛成空集
+ * ——「工具永久缺失」的根因，故一并移除。全部记忆/召回/时间线/落图能力由
+ * `cg(op=…)` / `stg(op=…)` 覆盖（见 src/lib/mdcg_client.ts 的显式映射）。 */
+export const CORE_TOOLS = [
+  'cg',   // md_cg 认知图统一入口（op 分发：route/read/recent/identity/verify/whitebox…）
+  'stg',  // md_cg 时空图入口（timeline/relation/anchor/consistency…）
+] as const
+
+/**
+ * 大脑模式工具集：`cg`/`stg` 基元 + md_cg 全部细粒度工具（`MDCG_MCP_SURFACE=full`）。
+ *
+ * 即「完整认知面」。不再区分身体/视觉——那些工具随 aeis 剥离，主仓无对应物。
+ * 管理类（forget / restore / review_decide）按映射表裁定「收窄后不留」，不在此列
+ * （如需显式启用，用 `tools: ['mdcg_forget', …]` 显式数组——显式配置不受 RISK 限制）。
+ */
+export const BRAIN_TOOLS = [
+  'cg', 'stg',
+  // 记忆读写
+  'mdcg_remember', 'mdcg_recall', 'mdcg_search', 'mdcg_get',
+  // 反思 / 验证 / 飞轮 / 负记忆
+  'mdcg_reflect', 'mdcg_verify', 'mdcg_flywheel', 'mdcg_mine_fix_pairs',
+  'mdcg_rejected', 'mdcg_unresolved',
+  // 审核队列（入队 / 列队 / 记录审计；裁决 review_decide 属管理类，不在此列）
+  'mdcg_propose', 'mdcg_review_list', 'mdcg_review_records',
+  // 保护 / 遗忘留痕（forget 属管理类，不在此列）
+  'mdcg_protect', 'mdcg_forgetting_history',
+  // 身份 / 一致性 / 元认知 / 自我状态
+  'mdcg_identity', 'mdcg_consistency', 'mdcg_metacognition', 'mdcg_self_state',
+  // 预测 / 因果 / 演化账本
+  'mdcg_predict', 'mdcg_causal', 'mdcg_evolution',
+  // 服务 / 状态
+  'mdcg_health', 'mdcg_whoami', 'mdcg_ingest', 'mdcg_watermarks',
+  'mdcg_whitebox', 'mdcg_service_info',
+] as const
+
+/** tools 配置：'core' | 'brain' | 'all' | 显式名称数组。 */
+export type ToolSelection = 'core' | 'brain' | 'all' | string[]
+
+/** P1 修复（GPT 审查）：只读/无副作用工具才允许并发——写操作（记忆/关系/
+ * 生命周期/摄取/学习）标 false，防止 DSH 并行调用导致 SQLite 写入竞争、
+ * 状态顺序错乱、关系边重复等。 */
+const READ_TOOLS = new Set([
+  // —— md_cg 细粒度只读工具（非多态：无 action 写分支）——
+  'mdcg_recall', 'mdcg_search', 'mdcg_get', 'mdcg_review_list', 'mdcg_review_records',
+  'mdcg_forgetting_history', 'mdcg_health', 'mdcg_whoami', 'mdcg_watermarks', 'mdcg_service_info',
+  // 注：cg / stg 是多态基元（op=focus/route 只读，op=write 写），一律按写处理（串行）。
+  // 多态工具（mdcg_predict/causal/evolution/protect/identity/self_state/whitebox…）
+  // 含 action=写 分支，同样保守按写处理。
+])
+
+/** 按工具名判定并发安全（只读查询 true；写操作 false） */
+export function isToolConcurrencySafe(name: string): boolean {
+  return READ_TOOLS.has(name)
+}
+
+/**
+ * P1 完善（GPT 审查·tools:all 自动扩权）：即使 selection='all' 也排除的宿主级
+ * 风险工具——此前后端新增工具即自动暴露给 Agent（动态扩权无 denylist）。
+ * 排除原则：宿主命令执行/权限终裁/外部设备/自主生命周期控制/角色卡写入。
+ * 显式名称数组（显式配置）不受此名单限制（配置者已明确选择）。
+ */
+export const RISK_TOOLS = new Set([
+  // —— md_cg 管理类（映射表裁定「收窄后不留」，需 can_admin）：即使 tools:'all'
+  //    也不自动暴露；要启用须用显式名称数组 ——
+  'mdcg_forget',        // 软删除（管理隔离：需 can_admin）
+  'mdcg_restore',       // 强恢复校验（管理隔离：需 can_admin）
+  'mdcg_review_decide', // 审核终裁（管理隔离：需 can_admin，等效设计者裁决）
+])
+
+/** 按配置筛选工具名（'all' 时排除 RISK_TOOLS 宿主级危险工具）。 */
+export function selectTools(all: string[], selection: ToolSelection): string[] {
+  if (selection === 'all') return all.filter((name) => !RISK_TOOLS.has(name))
+  const allowed = new Set(
+    selection === 'core' ? CORE_TOOLS
+      : selection === 'brain' ? BRAIN_TOOLS
+      : selection,
+  )
+  return all.filter((name) => allowed.has(name))
+}
+
+/** 把 MCP JSON Schema 的属性表转换为 ParameterSchemaSpec。 */
+export function schemaToParameters(inputSchema: Record<string, unknown> | undefined): ParameterSchemaSpec {
+  if (!inputSchema || typeof inputSchema !== 'object') return {}
+  const properties = inputSchema['properties'] as Record<string, unknown> | undefined
+  if (!properties || typeof properties !== 'object') return {}
+  const required = new Set(Array.isArray(inputSchema['required']) ? (inputSchema['required'] as string[]) : [])
+  const spec: Record<string, ParameterPropertySpec> = {}
+  for (const [key, raw] of Object.entries(properties)) {
+    const value = toValueSpec(raw)
+    if (required.has(key)) {
+      spec[key] = { ...value, required: true as const }
+    } else {
+      spec[key] = value
+    }
+  }
+  return spec
+}
+
+/** 递归转换单个 JSON Schema 节点为 ValueSchemaSpec。 */
+function toValueSpec(raw: unknown): ValueSchemaSpec {
+  if (typeof raw !== 'object' || raw === null) return { type: 'json' }
+  const node = raw as Record<string, unknown>
+  const annotations: { description?: string } = {}
+  if (typeof node['description'] === 'string') annotations.description = node['description'] as string
+  const type = node['type']
+  const enumValues = Array.isArray(node['enum']) ? (node['enum'] as unknown[]) : undefined
+  switch (type) {
+    case 'string':
+      return { type: 'string', ...annotations, ...(enumValues ? { enum: enumValues as string[] } : {}) }
+    case 'number':
+      return { type: 'number', ...annotations }
+    case 'integer':
+      return { type: 'integer', ...annotations }
+    case 'boolean':
+      return { type: 'boolean', ...annotations }
+    case 'null':
+      return { type: 'null', ...annotations }
+    case 'array': {
+      const spec: { type: 'array'; items?: ValueSchemaSpec } & typeof annotations = { type: 'array', ...annotations }
+      if (node['items'] !== undefined) spec.items = toValueSpec(node['items'])
+      return spec
+    }
+    case 'object': {
+      const props = schemaToParameters(node)
+      // P1 修复（GPT 审查）：尊重后端 additionalProperties 声明（false 保留），
+      // 不再无条件 true——此前后端写 false 也会被覆盖成 true，DSH 侧认为
+      // 参数合法但后端拒绝。
+      const additional = node['additionalProperties'] === false ? false : true
+      return { type: 'object', properties: props, additionalProperties: additional, ...annotations }
+    }
+    default:
+      return { type: 'json', ...annotations }
+  }
+}
+
+/** 从灵枢 content 数组中提取文本（MCP text block 拼接）。 */
+export function extractText(content: Array<{ type: string; text?: string; [key: string]: unknown }>): string {
+  return content
+    .map((block) => (block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
+    .filter(Boolean)
+    .join('\n')
+}
+
+/** 注册灵枢工具到 ctx.tools；返回取消注册函数。 */
+export async function registerLingshuTools(
+  ctx: Context,
+  bridge: LingshuBridge,
+  opts: { selection: ToolSelection; toolPrefix: string },
+): Promise<() => void> {
+  const tools = await bridge.listTools()
+  const wanted = new Set(selectTools(tools.map((t) => t.name), opts.selection))
+  const disposers: Array<() => void> = []
+  const registered: string[] = []
+  try {
+    for (const tool of tools) {
+      if (!wanted.has(tool.name)) continue
+      const publicName = `${opts.toolPrefix}${tool.name}`
+      const definition = defineTool({
+        name: publicName,
+        description: tool.description || `灵枢 ${tool.name}`,
+        parameters: schemaToParameters(tool.inputSchema),
+        output: {
+          schema: { type: 'json' } as never,
+          render(_args, value) {
+            return [{ type: 'text', text: extractText((value as McpCallResultLike).content ?? []) }]
+          },
+        },
+        timeoutMs: 120_000,
+        // P1 修复（GPT 审查）：按工具分类——只读查询可并发，写操作串行
+        isConcurrencySafe: () => isToolConcurrencySafe(tool.name),
+        // P1 修复（GPT 审查）：接收 exec.signal（用户取消/上层超时）——
+        // 此前完全忽略取消，取消后写操作（remember/relate/ingest 等）仍可能产生副作用
+        async execute(args: Record<string, unknown>, exec: { signal: AbortSignal }) {
+          if (exec.signal.aborted) throw new Error(`灵枢 ${tool.name} 已取消`)
+          const result = await bridge.callTool(tool.name, args as Record<string, unknown>, exec.signal)
+          if (exec.signal.aborted) throw new Error(`灵枢 ${tool.name} 已取消`)
+          if (result.isError) {
+            throw new Error(extractText(result.content) || `灵枢 ${tool.name} 执行失败`)
+          }
+          return { content: result.content } as never
+        },
+      })
+      disposers.push(ctx.tools.register(definition))
+      registered.push(publicName)
+    }
+  } catch (err) {
+    for (const dispose of disposers) dispose()
+    throw err
+  }
+  ctx.logger.info(`dsh-memory: 已注册 ${registered.length} 个灵枢工具（${registered.join(', ')}）`)
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+interface McpCallResultLike {
+  content: Array<{ type: string; text?: string; [key: string]: unknown }>
+}

package/zcode/AGENTS.md

@@ -1,12 +1,12 @@
-# 工作纪律（工作纪律_认知图条目_v1.1）· 17 条
+# 工作纪律（工作纪律_认知图条目_v1.1）· 18 条
 
 > 本文件由 `scripts/render_discipline.py` 从真源
 > `docs/工作纪律_认知图条目_v1.1.json` 渲染生成，**请勿手改**；改真源后重跑渲染。
-> 真源指纹（SHA256 前16位）：37aed1b5423c00af
+> 真源指纹（SHA256 前16位）：26bff32d73644699
 
 ## 概述
 
-工作纪律集: 4条方法论(理论先行/全面处理/白箱方法/根因) + 3条执行(验证/双副本/兜底) + 1条思考(中文思考/协作模式分级) + 1条保密(敏感信息隔离) + 3条图像线(选源护栏/历史查询优先/算法权威唯一) + 1条协作(访谈澄清:先问清再动手) + 1条合规(内容政策合规:公开产物过内容政策+隐私双清单) + 2条执行调度与运行环境(命令执行统一走python/UTF-8: 显式encoding+PYTHONUTF8=1, 规避GBK; 任务派发统一走蜂巢: 任何执行性任务经蜂巢spawn/submit执行并留痕, agent本体只做编排, L1出口=产物落点为只读判定(不改仓库/外部状态)可直跑须留痕) + 1条记忆闭环(任务收尾归档:每次任务执行完只将核心修改(内容/原因/位置/验证结论)按CCG六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 不写中间过程)
+工作纪律集: 4条方法论(理论先行/全面处理/白箱方法/根因) + 3条执行(验证/双副本/兜底) + 1条思考(中文思考/协作模式分级) + 1条保密(敏感信息隔离) + 3条图像线(选源护栏/历史查询优先/算法权威唯一) + 1条协作(访谈澄清:先问清再动手) + 1条合规(内容政策合规:公开产物过内容政策+隐私双清单) + 2条执行调度与运行环境(命令执行统一走python/UTF-8: 显式encoding+PYTHONUTF8=1, 规避GBK; 任务派发统一走蜂巢: 任何执行性任务经蜂巢spawn/submit执行并留痕, agent本体只做编排, L1出口=产物落点为只读判定(不改仓库/外部状态)可直跑须留痕) + 1条记忆闭环(任务收尾归档:每次任务执行完只将核心修改(内容/原因/位置/验证结论)按CCG六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 不写中间过程) + 1条信息获取(工作区索引优先: 查工作区文件先读 WORKSPACE_INDEX.md(仓根, 由 scripts/workspace_index.py 从 git 追踪面管线生成), 尚无则先跑 --write 生成再读, 不以重复全盘浏览代替; 索引是会陈化的手工件, 故须管线生成+机械守卫, 否则退化为误导源)
 
 ## 执行公约
 
@@ -139,6 +139,13 @@
 - **不适用**：纯会话内对话/问答(无执行动作)｜蜂巢不可用且任务必须立即执行(兜底须声明)｜L1只读判定(产物落点=不改仓库/不改外部状态的本地只读命令, 秒级·可逆·高频, 如跑门禁/测试/回归/lint看结论; 判据是产物落点而非「任务简单」的主观感受, 直跑须输出一行「L1 直跑：<命令> — 风险/频次/可逆性」留痕, 留痕粒度按任务(同一任务的多条只读命令合并为一条留痕, 不逐命令逐行); 层级归属的复核者=使用者+GitHub使用者)｜情感交互｜闲聊
 - **声明**：按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道, 兜底须声明。L1只读判定(产物落点=不改仓库/外部状态)可直跑, 须输出「L1 直跑：<命令> — 风险/频次/可逆性」留痕。
 
+### 18. 工作区索引优先
+
+- **触发**：查找工作区文件｜需要了解工作区结构｜跨目录检索定位｜长会话续接/上下文压缩后查找工作区文件
+- **动作**：定位工作区文件→先读 WORKSPACE_INDEX.md(仓根)→有则按表中职责/关键入口直接定位→无则先 python scripts/workspace_index.py --write 生成再读→守卫报陈化先重生成→不以重复全盘浏览代替; 新增顶层目录/根级文件须在脚本 DIR_ROLES/ROOT_FILES 登记后重生成; 上下文压缩/长会话续接后, 先 cg route『工作区索引』重建纪律视野(压缩会丢弃未留下执行痕迹的纪律, 只剩被声明过的条目——须主动召回)
+- **不适用**：已明确路径的单文件操作｜纯会话内对话/问答(无文件查找)｜仓外路径/系统路径(git 追踪面之外)
+- **声明**：按工作纪律第18条: 工作区索引优先——查工作区文件先读 WORKSPACE_INDEX.md(仓根, 管线生成); 无则先跑 scripts/workspace_index.py --write 生成再读, 不以重复全盘浏览代替。
+
 ## 声明出口（`response.direct` 原文 · 未输出即未执行）
 
 | # | 声明（response.direct 原文） |
@@ -160,6 +167,7 @@
 | 15 | 按工作纪律第15条: 命令执行统一走python——argv列表+显式UTF-8+PYTHONUTF8=1, 不经Windows shell, 规避GBK解码异常。 |
 | 16 | 按工作纪律第16条: 任务收尾归档——每次任务执行完只提炼核心修改(内容/原因/位置/验证结论)并按 CCG 六要素(功能名/生效条件/子功能/执行/验证方式/不适用条件)成文存入灵枢记忆, 写入后发起一次读取查询确认写入成功且可检索, 禁写中间过程/试错/调试等无效信息, 与第2条形成「查记忆→执行→写记忆→读回确认」闭环。 |
 | 17 | 按工作纪律第17条: 任务派发统一走蜂巢——任何执行性任务经蜂巢 spawn/submit 执行并留痕(spec/status/result), agent本体只做编排; 宿主自带subagent/team不是等价通道, 兜底须声明。L1只读判定(产物落点=不改仓库/外部状态)可直跑, 须输出「L1 直跑：<命令> — 风险/频次/可逆性」留痕。 |
+| 18 | 按工作纪律第18条: 工作区索引优先——查工作区文件先读 WORKSPACE_INDEX.md(仓根, 管线生成); 无则先跑 scripts/workspace_index.py --write 生成再读, 不以重复全盘浏览代替。 |
 
 ## 记忆接口速查（`cg` / `stg`）
 

package/zcode/README.md

@@ -1,41 +1,41 @@
-# ZCode 端 · 灵枢接入配置
-
-本目录 = **ZCode harness 专属配置**。ZCode 与 CodeBuddy 同构：在**会话起始读取项目根的 `AGENTS.md`**
-全文注入，因此本端产物同样采用 `full` 变体。
-
-## 目录内容
-
-| 文件 | 作用 | 性质 |
-|---|---|---|
-| `AGENTS.md` | 16 条工作纪律全文（会话起始注入） | **渲染产物**，勿手改 |
-| `README.md` | 本文件（接入说明） | 手写 |
-
-## 接入
-
-把 `zcode/AGENTS.md` 复制到**你项目的根目录**，新建会话即生效。
-
-ZCode 侧的记忆访问复用同一套 MCP 大脑，配置方式与 CodeBuddy 一致
-（见 [`../codebuddy/mcp.json`](../codebuddy/mcp.json) 与 [`../codebuddy/README.md`](../codebuddy/README.md)），
-只需把 `MDCG_ACTOR` 改为 `zcode`。
-
-该模板同源含第二条 MCP server `hive`（蜂巢：多智能体并发 + 任务上下文管理），一并合并即可；
-ZCode 与 CodeBuddy 指向同一仓库时**共享同一并发池**。语义与边界见
-[`../hive/README.md`](../hive/README.md) 的「各 harness 注册」。
-
-## 与 CodeBuddy 并存
-
-两者互不干扰——CodeBuddy 读根目录 `CODEBUDDY.md`，ZCode 读根目录 `AGENTS.md`；
-若项目同时使用两端，各自放入对应文件即可（内容同源，均为真源渲染产物）。
-
-## 记忆策略
-
-同 CodeBuddy 端：**只记重要内容（核心修改：内容/原因/位置/验证结论）+ 对话记录**，
-其余一律经写入闸门过滤。详见 [`../codebuddy/README.md`](../codebuddy/README.md) 的「记忆策略」一节。
-
-## 维护（面向灵枢维护者）
-
-- `AGENTS.md` 由 `scripts/render_discipline.py` 从**唯一真源** `docs/工作纪律_认知图条目_v1.1.json`
-  渲染生成，矩阵见 `docs/discipline/harnesses.yaml`（`zcode` 槽位）。
-- 改纪律 → 改真源 → `python scripts/render_discipline.py --target zcode --write`
-  → `python scripts/verify_discipline.py --target zcode` 通过 → 提交。
-- **手改本目录的 `AGENTS.md` 会被 `verify_discipline.py` 判为漂移**。
+# ZCode 端 · 灵枢接入配置
+
+本目录 = **ZCode harness 专属配置**。ZCode 与 CodeBuddy 同构：在**会话起始读取项目根的 `AGENTS.md`**
+全文注入，因此本端产物同样采用 `full` 变体。
+
+## 目录内容
+
+| 文件 | 作用 | 性质 |
+|---|---|---|
+| `AGENTS.md` | 16 条工作纪律全文（会话起始注入） | **渲染产物**，勿手改 |
+| `README.md` | 本文件（接入说明） | 手写 |
+
+## 接入
+
+把 `zcode/AGENTS.md` 复制到**你项目的根目录**，新建会话即生效。
+
+ZCode 侧的记忆访问复用同一套 MCP 大脑，配置方式与 CodeBuddy 一致
+（见 [`../codebuddy/mcp.json`](../codebuddy/mcp.json) 与 [`../codebuddy/README.md`](../codebuddy/README.md)），
+只需把 `MDCG_ACTOR` 改为 `zcode`。
+
+该模板同源含第二条 MCP server `hive`（蜂巢：多智能体并发 + 任务上下文管理），一并合并即可；
+ZCode 与 CodeBuddy 指向同一仓库时**共享同一并发池**。语义与边界见
+[`../hive/README.md`](../hive/README.md) 的「各 harness 注册」。
+
+## 与 CodeBuddy 并存
+
+两者互不干扰——CodeBuddy 读根目录 `CODEBUDDY.md`，ZCode 读根目录 `AGENTS.md`；
+若项目同时使用两端，各自放入对应文件即可（内容同源，均为真源渲染产物）。
+
+## 记忆策略
+
+同 CodeBuddy 端：**只记重要内容（核心修改：内容/原因/位置/验证结论）+ 对话记录**，
+其余一律经写入闸门过滤。详见 [`../codebuddy/README.md`](../codebuddy/README.md) 的「记忆策略」一节。
+
+## 维护（面向灵枢维护者）
+
+- `AGENTS.md` 由 `scripts/render_discipline.py` 从**唯一真源** `docs/工作纪律_认知图条目_v1.1.json`
+  渲染生成，矩阵见 `docs/discipline/harnesses.yaml`（`zcode` 槽位）。
+- 改纪律 → 改真源 → `python scripts/render_discipline.py --target zcode --write`
+  → `python scripts/verify_discipline.py --target zcode` 通过 → 提交。
+- **手改本目录的 `AGENTS.md` 会被 `verify_discipline.py` 判为漂移**。