@xdxer/dingtalk-agent 0.1.5-beta.1 → 0.1.5-beta.10

package/dist/src/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/workspace.ts"],"names":[],"mappings":"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","sourcesContent":["// Agent Workspace：一个物理目录对应一个稳定 Context/Field。\n// 人和模型读取 Markdown；机器控制状态仍留在宿主私有 JSON 中。\n\nimport {\n  existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync,\n} from 'node:fs'\nimport { basename, dirname, join, relative, resolve } from 'node:path'\nimport { digest } from './events.js'\nimport * as dws from './dws.js'\n\nexport const WORKSPACE_FILE = '.dingtalk-agent/workspace.json'\n\nexport interface WorkspaceSpec {\n  $schema: 'dingtalk-agent/workspace@1'\n  id: string\n  contextId: string\n  fieldId: string\n  dws: { profile: string; expectedUserId: string }\n  skills: string[]\n  mounts: Record<'profile' | 'memory' | 'knowledge' | 'skills', string>\n}\n\nexport interface WorkspaceInitOptions {\n  contextId?: string\n  id?: string\n  memory?: string\n  knowledge?: string\n}\n\nexport interface MountSnapshot {\n  slot: string\n  provider: 'local-md' | 'local-dir' | 'dingtalk-doc'\n  source: string\n  snapshotPath: string\n  hash: string\n}\n\nexport function workspacePath(root: string): string {\n  return join(root, WORKSPACE_FILE)\n}\n\nexport function ensureWorkspace(\n  root: string,\n  options: WorkspaceInitOptions = {},\n): WorkspaceSpec {\n  const path = workspacePath(root)\n  if (existsSync(path)) {\n    const current = loadWorkspace(root)\n    if (options.contextId && options.contextId !== current.contextId) {\n      throw new Error(\n        `当前目录已绑定 contextId=${current.contextId}；一个物理 Workspace 不能重新绑定为 ${options.contextId}`,\n      )\n    }\n    return current\n  }\n\n  const contextId = clean(options.contextId || basename(resolve(root)) || 'default')\n  const id = clean(options.id || contextId)\n  const spec: WorkspaceSpec = {\n    $schema: 'dingtalk-agent/workspace@1',\n    id,\n    contextId,\n    fieldId: 'default',\n    dws: { profile: '', expectedUserId: '' },\n    // 用 Skill name 声明，不把 Workspace 绑死到某个物理安装目录。\n    // Resolver 依次查 Workspace override、全局安装和 npm 内置版本。\n    skills: ['dingtalk-basic-behavior', ...discoverLocalSkillNames(root)],\n    mounts: {\n      profile: existsSync(join(root, 'AGENTS.md'))\n        ? 'local-md:AGENTS.md' : 'local-md:WORKSPACE.md',\n      memory: options.memory || 'local-md:MEMORY.md',\n      knowledge: options.knowledge || 'local-md:knowledge/INDEX.md',\n      skills: 'local-dir:skills',\n    },\n  }\n\n  mkdirSync(dirname(path), { recursive: true })\n  writeFileSync(path, JSON.stringify(spec, null, 2) + '\\n', { flag: 'wx' })\n  writeDefaultMarkdown(root, spec)\n  for (const dir of ['.dingtalk-agent/cache', '.dingtalk-agent/pending']) {\n    mkdirSync(join(root, dir), { recursive: true })\n  }\n  return spec\n}\n\nexport function loadWorkspace(root: string): WorkspaceSpec {\n  const path = workspacePath(root)\n  if (!existsSync(path)) {\n    throw new Error(\n      '缺少 .dingtalk-agent/workspace.json；只有 Prepared Run runtime 才需要 `dingtalk-agent init`。' +\n      '普通 Agent Session 请使用全局 Skill，按需运行 `dingtalk-agent bootstrap`。',\n    )\n  }\n  let value: unknown\n  try { value = JSON.parse(readFileSync(path, 'utf8')) }\n  catch (error) { throw new Error(`Workspace manifest 不是合法 JSON: ${error.message}`) }\n  return validateWorkspace(value)\n}\n\nexport function resolveContextId(spec: WorkspaceSpec, supplied = ''): string {\n  const contextId = clean(supplied || spec.contextId)\n  if (contextId !== spec.contextId) {\n    throw new Error(\n      `contextId=${contextId} 不属于当前 Workspace（期望 ${spec.contextId}）；请由上游选择正确工作目录`,\n    )\n  }\n  return contextId\n}\n\n/**\n * Provider 只负责把语义内容冻结成本地 Markdown；锁、Wait、去重和 Receipt 不走这里。\n * dingtalk-doc 只读显式 node，不搜索、不创建、不覆盖。\n */\nexport function snapshotWorkspaceMounts(\n  root: string,\n  runPath: string,\n  spec: WorkspaceSpec,\n): MountSnapshot[] {\n  const destination = join(runPath, 'context', 'mounts')\n  mkdirSync(destination, { recursive: true })\n  const snapshots: MountSnapshot[] = []\n\n  for (const [slot, uri] of Object.entries(spec.mounts)) {\n    const mount = parseMount(uri)\n    if (mount.provider === 'local-dir') {\n      // skills 是逻辑槽：实际内容由 Skill resolver 从 Workspace override、\n      // 全局目录或 npm 内置版本解析并在 Session 创建时冻结。\n      if (slot !== 'skills') safeLocalPath(root, mount.ref)\n      snapshots.push({\n        slot, provider: mount.provider, source: uri,\n        // P0 的目录型 mount 只有 skills；真实内容由 Session 绑定并冻结到这里。\n        snapshotPath: slot === 'skills' ? 'context/skills' : '', hash: '',\n      })\n      continue\n    }\n\n    const markdown = mount.provider === 'local-md'\n      ? readFileSync(safeLocalPath(root, mount.ref), 'utf8')\n      : String(dws.readDoc(mount.ref, spec.dws.profile))\n    const path = join(destination, `${safeName(slot)}.md`)\n    writeFileSync(path, markdown.endsWith('\\n') ? markdown : markdown + '\\n')\n    snapshots.push({\n      slot,\n      provider: mount.provider,\n      source: uri,\n      snapshotPath: relative(runPath, path).split('\\\\').join('/'),\n      hash: digest(markdown),\n    })\n  }\n\n  writeFileSync(\n    join(destination, 'manifest.json'),\n    JSON.stringify({ $schema: 'dingtalk-agent/mount-snapshot@1', entries: snapshots }, null, 2) + '\\n',\n  )\n  return snapshots\n}\n\nfunction validateWorkspace(value: unknown): WorkspaceSpec {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new Error('Workspace manifest 必须是 JSON object')\n  }\n  const input = value as Record<string, any>\n  if (input.$schema !== 'dingtalk-agent/workspace@1') {\n    throw new Error('Workspace manifest 缺少 dingtalk-agent/workspace@1 schema')\n  }\n  for (const key of ['id', 'contextId', 'fieldId']) {\n    if (!clean(input[key])) throw new Error(`Workspace manifest 缺少 ${key}`)\n  }\n  if (!Array.isArray(input.skills) || input.skills.some((item: unknown) => typeof item !== 'string')) {\n    throw new Error('Workspace skills 必须是 string[]')\n  }\n  if (!input.dws || typeof input.dws.profile !== 'string' ||\n      typeof input.dws.expectedUserId !== 'string') {\n    throw new Error('Workspace dws 必须包含 string profile / expectedUserId')\n  }\n  const requiredSlots = ['profile', 'memory', 'knowledge', 'skills']\n  if (!input.mounts || requiredSlots.some((slot) => typeof input.mounts[slot] !== 'string')) {\n    throw new Error(`Workspace mounts 必须包含 ${requiredSlots.join(' / ')}`)\n  }\n  for (const uri of Object.values(input.mounts)) parseMount(String(uri))\n  return input as WorkspaceSpec\n}\n\nfunction parseMount(uri: string): {\n  provider: 'local-md' | 'local-dir' | 'dingtalk-doc'\n  ref: string\n} {\n  const separator = uri.indexOf(':')\n  const provider = uri.slice(0, separator)\n  const ref = separator >= 0 ? uri.slice(separator + 1).trim() : ''\n  if (!['local-md', 'local-dir', 'dingtalk-doc'].includes(provider) || !ref) {\n    throw new Error(`不支持的 Workspace mount: ${uri}`)\n  }\n  return { provider: provider as 'local-md' | 'local-dir' | 'dingtalk-doc', ref }\n}\n\nfunction safeLocalPath(root: string, ref: string): string {\n  const rootReal = realpathSync(resolve(root))\n  const candidate = resolve(rootReal, ref)\n  if (!existsSync(candidate)) throw new Error(`Workspace mount 不存在: ${ref}`)\n  const actual = realpathSync(candidate)\n  const rel = relative(rootReal, actual)\n  if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\\\' : '/'}`)) {\n    throw new Error(`Workspace local mount 必须位于当前目录内: ${ref}`)\n  }\n  return actual\n}\n\nfunction writeDefaultMarkdown(root: string, spec: WorkspaceSpec): void {\n  const files: Array<[string, string]> = [\n    ['WORKSPACE.md', `# Agent Workspace\\n\\n- Context ID: ${spec.contextId}\\n- Workspace: ${spec.id}\\n- Field: ${spec.fieldId}\\n\\n这里定义稳定的身份、职责、协作边界和内容挂载。\\n`],\n    ['MEMORY.md', '# Long-term Memory\\n\\n只保存经过筛选、带来源的长期记忆。当前事项放在 Session memory。\\n'],\n    ['knowledge/INDEX.md', '# Knowledge Index\\n\\n按需列出本 Workspace 可用的知识入口。\\n'],\n  ]\n  for (const [rel, content] of files) {\n    const path = join(root, rel)\n    mkdirSync(dirname(path), { recursive: true })\n    if (!existsSync(path)) writeFileSync(path, content)\n  }\n}\n\nfunction safeName(value: string): string {\n  return value.replace(/[^a-zA-Z0-9._-]+/g, '-')\n}\n\nfunction discoverLocalSkillNames(root: string): string[] {\n  const directory = join(root, 'skills')\n  if (!existsSync(directory) || !lstatSync(directory).isDirectory()) return []\n  const names: string[] = []\n  for (const entry of readdirSync(directory, { withFileTypes: true })) {\n    if (!entry.isDirectory()) continue\n    const path = join(directory, entry.name, 'SKILL.md')\n    if (!existsSync(path)) continue\n    const markdown = readFileSync(path, 'utf8')\n    const frontmatter = markdown.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---/)?.[1] || ''\n    const name = frontmatter.match(/^name:\\s*['\"]?([^'\"\\r\\n]+)['\"]?\\s*$/m)?.[1]?.trim() || ''\n    if (!name) throw new Error(`本地 Role Skill 缺少 frontmatter name: ${path}`)\n    if (name !== entry.name) {\n      throw new Error(`本地 Role Skill 目录名与 name 不一致: ${entry.name} != ${name}`)\n    }\n    if (name !== 'dingtalk-basic-behavior') names.push(name)\n  }\n  return [...new Set(names)].sort()\n}\n\nfunction clean(value: unknown): string {\n  return typeof value === 'string' ? value.trim() : ''\n}\n"]}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/workspace.ts"],"names":[],"mappings":"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","sourcesContent":["// Agent Workspace：一个物理目录对应一个稳定 Context/Field。\n// 人和模型读取 Markdown；机器控制状态仍留在宿主私有 JSON 中。\n\nimport {\n  existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync,\n} from 'node:fs'\nimport { basename, dirname, join, relative, resolve } from 'node:path'\nimport { digest } from './events.js'\nimport * as dws from './dws.js'\n\nexport const WORKSPACE_FILE = '.dingtalk-agent/workspace.json'\n\nexport interface WorkspaceSpec {\n  $schema: 'dingtalk-agent/workspace@1'\n  id: string\n  contextId: string\n  fieldId: string\n  dws: { profile: string; expectedUserId: string }\n  skills: string[]\n  mounts: Record<'profile' | 'memory' | 'knowledge' | 'skills', string>\n}\n\nexport interface WorkspaceInitOptions {\n  contextId?: string\n  id?: string\n  memory?: string\n  knowledge?: string\n}\n\nexport interface MountSnapshot {\n  slot: string\n  provider: 'local-md' | 'local-dir' | 'dingtalk-doc'\n  source: string\n  snapshotPath: string\n  hash: string\n}\n\nexport function workspacePath(root: string): string {\n  return join(root, WORKSPACE_FILE)\n}\n\nexport function ensureWorkspace(\n  root: string,\n  options: WorkspaceInitOptions = {},\n): WorkspaceSpec {\n  const path = workspacePath(root)\n  if (existsSync(path)) {\n    const current = loadWorkspace(root)\n    if (options.contextId && options.contextId !== current.contextId) {\n      throw new Error(\n        `当前目录已绑定 contextId=${current.contextId}；一个物理 Workspace 不能重新绑定为 ${options.contextId}`,\n      )\n    }\n    return current\n  }\n\n  const contextId = clean(options.contextId || basename(resolve(root)) || 'default')\n  const id = clean(options.id || contextId)\n  const packagedDefinition = existsSync(join(root, 'agent', 'AGENTS.md'))\n  const profileRef = packagedDefinition\n    ? 'agent/AGENTS.md'\n    : existsSync(join(root, 'AGENTS.md')) ? 'AGENTS.md' : 'WORKSPACE.md'\n  const skillsRef = existsSync(join(root, 'agent', 'skills'))\n    ? 'agent/skills' : 'skills'\n  const spec: WorkspaceSpec = {\n    $schema: 'dingtalk-agent/workspace@1',\n    id,\n    contextId,\n    fieldId: 'default',\n    dws: { profile: '', expectedUserId: '' },\n    // 用 Skill name 声明，不把 Workspace 绑死到某个物理安装目录。\n    // Resolver 依次查 Workspace override、全局安装和 npm 内置版本。\n    skills: ['dta-basic-behavior', ...discoverLocalSkillNames(root, skillsRef)],\n    mounts: {\n      profile: `local-md:${profileRef}`,\n      memory: options.memory || 'local-md:MEMORY.md',\n      knowledge: options.knowledge || 'local-md:knowledge/INDEX.md',\n      skills: `local-dir:${skillsRef}`,\n    },\n  }\n\n  mkdirSync(dirname(path), { recursive: true })\n  writeFileSync(path, JSON.stringify(spec, null, 2) + '\\n', { flag: 'wx' })\n  writeDefaultMarkdown(root, spec)\n  for (const dir of ['.dingtalk-agent/cache', '.dingtalk-agent/pending']) {\n    mkdirSync(join(root, dir), { recursive: true })\n  }\n  return spec\n}\n\nexport function loadWorkspace(root: string): WorkspaceSpec {\n  const path = workspacePath(root)\n  if (!existsSync(path)) {\n    throw new Error(\n      '缺少 .dingtalk-agent/workspace.json；只有 Prepared Run runtime 才需要 `dingtalk-agent init`。' +\n      '普通 Agent Session 请使用全局 Skill，按需运行 `dingtalk-agent bootstrap`。',\n    )\n  }\n  let value: unknown\n  try { value = JSON.parse(readFileSync(path, 'utf8')) }\n  catch (error) { throw new Error(`Workspace manifest 不是合法 JSON: ${error.message}`) }\n  return validateWorkspace(value)\n}\n\nexport function resolveContextId(spec: WorkspaceSpec, supplied = ''): string {\n  const contextId = clean(supplied || spec.contextId)\n  if (contextId !== spec.contextId) {\n    throw new Error(\n      `contextId=${contextId} 不属于当前 Workspace（期望 ${spec.contextId}）；请由上游选择正确工作目录`,\n    )\n  }\n  return contextId\n}\n\n/**\n * Provider 只负责把语义内容冻结成本地 Markdown；锁、Wait、去重和 Receipt 不走这里。\n * dingtalk-doc 只读显式 node，不搜索、不创建、不覆盖。\n */\nexport function snapshotWorkspaceMounts(\n  root: string,\n  runPath: string,\n  spec: WorkspaceSpec,\n): MountSnapshot[] {\n  const destination = join(runPath, 'context', 'mounts')\n  mkdirSync(destination, { recursive: true })\n  const snapshots: MountSnapshot[] = []\n\n  for (const [slot, uri] of Object.entries(spec.mounts)) {\n    const mount = parseMount(uri)\n    if (mount.provider === 'local-dir') {\n      // skills 是逻辑槽：实际内容由 Skill resolver 从 Workspace override、\n      // 全局目录或 npm 内置版本解析并在 Session 创建时冻结。\n      if (slot !== 'skills') safeLocalPath(root, mount.ref)\n      snapshots.push({\n        slot, provider: mount.provider, source: uri,\n        // P0 的目录型 mount 只有 skills；真实内容由 Session 绑定并冻结到这里。\n        snapshotPath: slot === 'skills' ? 'context/skills' : '', hash: '',\n      })\n      continue\n    }\n\n    const markdown = mount.provider === 'local-md'\n      ? readFileSync(safeLocalPath(root, mount.ref), 'utf8')\n      : String(dws.readDoc(mount.ref, spec.dws.profile))\n    const path = join(destination, `${safeName(slot)}.md`)\n    writeFileSync(path, markdown.endsWith('\\n') ? markdown : markdown + '\\n')\n    snapshots.push({\n      slot,\n      provider: mount.provider,\n      source: uri,\n      snapshotPath: relative(runPath, path).split('\\\\').join('/'),\n      hash: digest(markdown),\n    })\n  }\n\n  writeFileSync(\n    join(destination, 'manifest.json'),\n    JSON.stringify({ $schema: 'dingtalk-agent/mount-snapshot@1', entries: snapshots }, null, 2) + '\\n',\n  )\n  return snapshots\n}\n\nfunction validateWorkspace(value: unknown): WorkspaceSpec {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new Error('Workspace manifest 必须是 JSON object')\n  }\n  const input = value as Record<string, any>\n  if (input.$schema !== 'dingtalk-agent/workspace@1') {\n    throw new Error('Workspace manifest 缺少 dingtalk-agent/workspace@1 schema')\n  }\n  for (const key of ['id', 'contextId', 'fieldId']) {\n    if (!clean(input[key])) throw new Error(`Workspace manifest 缺少 ${key}`)\n  }\n  if (!Array.isArray(input.skills) || input.skills.some((item: unknown) => typeof item !== 'string')) {\n    throw new Error('Workspace skills 必须是 string[]')\n  }\n  if (!input.dws || typeof input.dws.profile !== 'string' ||\n      typeof input.dws.expectedUserId !== 'string') {\n    throw new Error('Workspace dws 必须包含 string profile / expectedUserId')\n  }\n  const requiredSlots = ['profile', 'memory', 'knowledge', 'skills']\n  if (!input.mounts || requiredSlots.some((slot) => typeof input.mounts[slot] !== 'string')) {\n    throw new Error(`Workspace mounts 必须包含 ${requiredSlots.join(' / ')}`)\n  }\n  for (const uri of Object.values(input.mounts)) parseMount(String(uri))\n  return input as WorkspaceSpec\n}\n\nfunction parseMount(uri: string): {\n  provider: 'local-md' | 'local-dir' | 'dingtalk-doc'\n  ref: string\n} {\n  const separator = uri.indexOf(':')\n  const provider = uri.slice(0, separator)\n  const ref = separator >= 0 ? uri.slice(separator + 1).trim() : ''\n  if (!['local-md', 'local-dir', 'dingtalk-doc'].includes(provider) || !ref) {\n    throw new Error(`不支持的 Workspace mount: ${uri}`)\n  }\n  return { provider: provider as 'local-md' | 'local-dir' | 'dingtalk-doc', ref }\n}\n\nfunction safeLocalPath(root: string, ref: string): string {\n  const rootReal = realpathSync(resolve(root))\n  const candidate = resolve(rootReal, ref)\n  if (!existsSync(candidate)) throw new Error(`Workspace mount 不存在: ${ref}`)\n  const actual = realpathSync(candidate)\n  const rel = relative(rootReal, actual)\n  if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\\\' : '/'}`)) {\n    throw new Error(`Workspace local mount 必须位于当前目录内: ${ref}`)\n  }\n  return actual\n}\n\nfunction writeDefaultMarkdown(root: string, spec: WorkspaceSpec): void {\n  const files: Array<[string, string]> = [\n    ['WORKSPACE.md', `# Agent Workspace\\n\\n- Context ID: ${spec.contextId}\\n- Workspace: ${spec.id}\\n- Field: ${spec.fieldId}\\n\\n这里定义稳定的身份、职责、协作边界和内容挂载。\\n`],\n    ['MEMORY.md', '# Long-term Memory\\n\\n只保存经过筛选、带来源的长期记忆。当前事项放在 Session memory。\\n'],\n    ['knowledge/INDEX.md', '# Knowledge Index\\n\\n按需列出本 Workspace 可用的知识入口。\\n'],\n  ]\n  for (const [rel, content] of files) {\n    const path = join(root, rel)\n    mkdirSync(dirname(path), { recursive: true })\n    if (!existsSync(path)) writeFileSync(path, content)\n  }\n}\n\nfunction safeName(value: string): string {\n  return value.replace(/[^a-zA-Z0-9._-]+/g, '-')\n}\n\nfunction discoverLocalSkillNames(root: string, skillsRef: string): string[] {\n  const directory = join(root, skillsRef)\n  if (!existsSync(directory) || !lstatSync(directory).isDirectory()) return []\n  const names: string[] = []\n  for (const entry of readdirSync(directory, { withFileTypes: true })) {\n    if (!entry.isDirectory()) continue\n    const path = join(directory, entry.name, 'SKILL.md')\n    if (!existsSync(path)) continue\n    const markdown = readFileSync(path, 'utf8')\n    const frontmatter = markdown.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---/)?.[1] || ''\n    const name = frontmatter.match(/^name:\\s*['\"]?([^'\"\\r\\n]+)['\"]?\\s*$/m)?.[1]?.trim() || ''\n    if (!name) throw new Error(`本地 Role Skill 缺少 frontmatter name: ${path}`)\n    if (name !== entry.name) {\n      throw new Error(`本地 Role Skill 目录名与 name 不一致: ${entry.name} != ${name}`)\n    }\n    if (name !== 'dta-basic-behavior') names.push(name)\n  }\n  return [...new Set(names)].sort()\n}\n\nfunction clean(value: unknown): string {\n  return typeof value === 'string' ? value.trim() : ''\n}\n"]}

package/docs/AGENT-IN-PRODUCTION.md

@@ -0,0 +1,255 @@
+# 交付之后：一个数字员工在生产上是什么样
+
+> 给**接手一个已经在跑的 Agent** 的人或 Coding Agent。
+>
+> [ARCHITECTURE](ARCHITECTURE.md) 回答"一个数字员工由什么构成、每件事谁说了算"——那是**设计视角**。
+> 本文回答"它交付之后，一天到底怎么转、坏起来长什么样、你去哪看"——**运行视角**。
+> 两篇不重复：设计视角讲边界为什么这么划，运行视角讲这些边界在生产上呈现成什么现象。
+>
+> 装机与升级见 [Installation](INSTALLATION.md)；评测方法见 [Self-test](SELF-TEST.md)；
+> 行为协议正本见 [`dta-basic-behavior`](../skills/core/dta-basic-behavior/SKILL.md)。
+
+---
+
+## 0. 一句话
+
+**它没有常驻进程。** 每一次"活过来"都是一个全新的、一次性的沙箱：装配 Skill → 干一件事 → 消失。
+两次运行之间它什么都不记得。
+
+这一条推出下面所有内容。**记忆不在模型里，全部在外部权威上**——落不到权威上的事，等于没发生。
+
+---
+
+## 1. 一天里它被叫醒几次、被谁叫醒
+
+三类唤醒源，语义完全不同（分类与权威归属见 [ARCHITECTURE §3.1](ARCHITECTURE.md#31-驱动一个数字员工怎么被叫醒)）：
+
+| 唤醒源 | 有人在等吗 | 常态 | 失败的代价 |
+|---|---|---|---|
+| **IM · @ 或单聊** | 有 | 该回一句（先过响应资格判断） | 用户直接看见 |
+| **IM · 群里没 @ 它** | 不一定 | **默认 `silence`**——群消息未 @ 不擅自插话（响应资格由 Basic 判） | 乱插话反而是错 |
+| **常驻节律**（平台 schedule） | 没有 | **静默** | 没人看见，会积压 |
+| **受控任务**（平台 issue / 开发者派活） | 有，异步 | 有 issue 可回读 | 在平台上看得见 |
+
+> 「有人在等就回」不等于「群里每句都回」。**响应资格先于一切**——@ 或单聊才默认该回，
+> 群里没点名默认 `silence`，判据在 `dta-basic-behavior`，别把"有人在等"简化成"必须回一句"。
+
+**运行时的量级差得很远。** 以本仓库的参考实现「FDE 教练」2026-07-23 一天为例：
+IM 对话 **39 轮**，节律唤醒 **111 次**——**节律是 IM 的三倍**。
+这是数字员工与聊天机器人最大的运行时差别：**它大部分时间在没人看的时候干活。**
+
+只声明节律是不够的，要能读回来：
+
+```bash
+dta schedule show                       # 只读【本地 manifest 声明】的节律 + 静态校验(同刻/完成判据)
+dta schedule plan --workspace <name>    # 把声明映射成 provider 该执行的 reconcile 命令
+```
+
+> ⚠️ **这两条读的是【声明态】（本地 `dingtalk-agent.json`），不是平台的【实际态】。** 它们只 `inspectAgentProject`，不查 provider——`plan` 也只是打印该由 ops 技能执行的对账命令。排障时想知道**线上真实生效的节律**，要走 provider 回读（Multica 走 `dta-ops-multica` 的 `autopilot-list`），别拿一份可能没 apply 的 manifest 当线上真相。
+
+> **`dta deploy` 不创建也不修改节律。** 节律属于平台，增删由 operator 执行。
+> 这不是缺功能，是边界：Agent 不自建定时器、不自改节律（[ARCHITECTURE §3.1](ARCHITECTURE.md#31-驱动一个数字员工怎么被叫醒)）。
+
+**排节律时的四条经验**（都从真实生产换来，`dta schedule show/plan` 会静态检出前两条）：
+
+1. **每条节律必须有数据派生的完成判据（`completion`）。** 没有它就只能靠"那一拍跑没跑"判完成，而平台会漏拍、会跳过迟到过久的 fire——一次抖动就永久丢一期。`schedule show` 缺 `completion` 会告警。
+2. **两拍不得在同一时刻 fire。** 外发拍的送达回执是发完才写、没有锁，同刻并发会把同一条消息发两遍给第三方。（只错开分钟不够看——要看分钟×小时真不真相交。**也别用两个时区写节律**：`0 9 * * *`@Asia/Shanghai 和 `0 1 * * *`@UTC 是同一时刻，本地换算不了，`schedule show/plan` 一律当撞车挡住。全 Agent 统一一个 timezone。）
+3. **有时效的轻活排前，别让重活把它饿死。** 一拍预算有限。把每次都超时的重活排在序列最前，排它后面的轻活（对账、收件）会整轮轮不到——真事故：夜拍里留痕对账排第 7 位、前面的夜间重建每拍超时，结果留痕对账整夜没跑到。**正解**：有时效/轻的排前面，或给重活单独一条节律、独立预算，别和轻活挤同一拍。
+4. **入口是脉冲、出口是均匀——产能按峰值窗口算，不按日均。** 用户往往集中在某个时段涌入，而节律是固定频率。按日总量算"够用"会在高峰那几小时实际欠账。
+
+---
+
+## 2. 值班 ≠ 任务：运行上最常见的一组混淆
+
+| | **值班（duty）** | **任务（task）** |
+|---|---|---|
+| 本质 | 永远做不完的**维护义务** | 有终态的**一件事** |
+| 完成判据 | **从数据派生**（水位 ≥ 今天 / backlog = 0） | 对象自身的终态（如 Todo `isDone`） |
+| 状态存哪 | **不存**。索引本身就是完成状态 | 存在那个对象上 |
+| 漏一次 | 下一拍自愈 | 断链，**而且不自知** |
+
+**为什么完成判据必须数据派生**：拍是无状态的、会漏、会被平台跳过、会换实例。
+"今晚跑过没有"这个问题只有数据能回答。不记状态、不建标记、不上锁、不信会话记忆。
+
+这条有一个几乎所有人都会踩的推论：
+
+> **任何「某时刻必须发生」的事，判据只能是「今天/本周它发生了没有」，不能是「那一拍跑了没有」。**
+
+托管平台普遍会塌缩漏掉的 fire、跳过迟到过久的 fire。把判据绑在"某一拍"上，一次 runtime 抖动就永久丢一期，
+事后还查不出来。
+
+---
+
+## 3. 两阶段值班：命令给清单，模型干活
+
+这是生产上最容易出事的一类，值得单独知道。
+
+- **一阶段**：命令跑完，活就干完了（重建索引、对账、汇总）。
+- **两阶段**：命令吐出来的是**待办清单**，真正的活是模型自己做——读全文 → 生成 → 逐条写回。
+
+于是：
+
+> **这一拍到底做没做，只看它发出了几次写调用——不看它跑了几次命令。**
+> 没有对应的写调用，就不许在自述里写「已处理 N 条」。
+
+**为什么把这条写这么重**：谎报比不做更糟。不做，backlog 明摆着；谎报，backlog 在"已完成"的假象下
+无限积压，**没有任何人会发现**。
+
+配套的监督必须**绕开自述**：直接算准 backlog，和上一次快照比趋势。跑了多拍而 backlog 没往下走，就报警。
+**写没写，用数据判，编不了。**
+
+---
+
+## 4. backlog 是队列：只看净值会误诊
+
+两阶段值班的积压本质是队列，三个数字才够用：
+
+```text
+入口速率 = 单位时间新进来的活
+出口速率 = 单位时间真被写掉的活
+净值     = 入口 − 出口
+```
+
+**健康不是「backlog 小」，是「出口 ≥ 入口」。** 净值长期为正，backlog 多大都只是时间问题。
+
+只看净值分不清四种病，而它们的处方完全不同：
+
+| 现象 | 病 | 处方 |
+|---|---|---|
+| 入 40，出 0 | 空转，或**写在了错的地方** | 查写调用到底落在哪一行 |
+| 入 40，出 15 | 产能不足 | 加拍、加批量 |
+| 入 40，出 40，backlog 不降 | 打平但清不掉历史欠账 | 要额外产能，或削入口 |
+| 入 0，出 0 | 可能是**空读**（见 §5） | 先别判，下轮再看 |
+
+**拆的办法很便宜**：对 backlog 的**键集合**做前后两次差分——本次在、上次不在 = 入口；上次在、本次不在 = 出口。
+
+还有两条运行时经验：
+
+- **入口通常是脉冲的，出口是均匀的。** 只按日总量算产能会得到"够用"的错觉，而高峰那几小时实际在欠。
+- **队列有头，头会堵。** 若实现是"先补最旧的一天"，那一天一旦因为数据缺陷清不掉，**后面全部够不着**，
+  而每一拍的写回都"成功"。这类故障的表征是：写调用一直在发、成功率 100%、backlog 纹丝不动。
+
+---
+
+## 5. 生产上的四类假信号
+
+按危险程度排序。**它们的共同点是：都伪装成成功。**
+
+1. **报 0 的 ✅ 不可信。** `活跃 0 人`、`0 行`、`待处理 0 条`——判据往往是结构性的
+   （`集合为空 → backlog 为空 → done=True`），**于是任何一次读表失败都会变成一个自信的 ✅**。
+   规则：报 0 的那一项不算做过，下一轮照常再来（它幂等），同时记降级并点名。
+2. **写后回读读的是同一个错误对象。** 回读校验只有在**独立定位**目标时才有效。
+   若写 `rows[0]`、回读也取 `rows[0]`，则永远自洽、永远发现不了写错了行。
+3. **两个完成判据分开写，迟早会漂。** 同一件事若在两处各判一次，一处说"没完成"、一处说"全好了"，
+   而调用方只问其中一个——补救路径就再也不会被触发，且没有任何一层报警。
+   **同一个语义只留一个谓词，两个调用方共用。**
+4. **命令被沙箱砍掉时不会留痕。** 留痕通常写在动作**之后**，被砍时那行根本没执行，
+   事后看就像"这一拍没跑过"。超时后必须补一行降级。
+
+失败要说人话，四个状态别混：
+
+| 状态 | 什么时候用 | 什么时候**不能**用 |
+|---|---|---|
+| `pass` | 真做成了，**且独立回读确认过** | "我试过了" |
+| `degraded` | 做了一部分 / 被超时砍掉 / 读到可疑空集 | — |
+| `fail` | 明确失败 | — |
+| `blocked` | 缺上游前提（权限、配置、目标不存在） | 含糊报"出错了" |
+
+**没送达就写 `pass`，比链条断掉更糟**——断链至少看得出来"今天没跑"。
+
+---
+
+## 6. 钱：先知道哪一块是看不见的
+
+托管平台通常只记 Token，不记钱；把 Token 折成钱是**调用方的责任**，需要一份人工维护、带来源与日期的费率表。
+
+运行时最重要的一件事是**知道盲区在哪**：
+
+> **不产生 issue 的节律唤醒，平台往往没有可查的用量记录。**
+> 于是报表上的成本是**低报**的，而且低报的比例可能比可见部分还大。
+
+两条纪律：
+
+- **缺价的模型登记成 `unpriced` 并让报表直接失败**，不要按 0 计——按 0 计会让成本看起来更便宜，是最危险的失败方式。
+- 节律的 `mode` 直接决定可计量性。**改 `mode` 就是在改计量口径**，要同步改报表说明，否则会重复计或漏计。
+  （`dta schedule show/plan` 现在会给每条节律标 `metered`，ephemeral 不记账的会显式提示。）
+
+### 观测这一层，dta 不替你造——但有可抄的范式
+
+[ARCHITECTURE §8 ⑥](ARCHITECTURE.md#8-开发生命周期从定义到观测) 讲得很直白：**用量计量（交互量、任务量、线上 token、成本、按人按群分布）dta 一项都没实现**，`dta observe` 只是人工脱敏观察绑版本、不采线上数据；执行轨迹读取属平台（薄 wrapper，换平台即失效）；连完成证据的**签发**都还没接进公开 CLI（`dta task` 只有 show/checkpoint）。
+
+所以观测是 **Agent 自己该建的一层**。目前最完整的参考实现是「FDE 教练」，它用三样东西把自己变得可观测，都可复用：
+
+1. **一张运行记录表 = 每个 Run 一行，只增不改**。问了什么、答了什么、花了多久、成败、证据、issue/会话/消息硬 ID 全落进去。它是日报、审计、"昨天到底发生了什么"的唯一来源。**没有它，一次运行事后等于没发生过。**
+2. **一张费率表 + 只读成本报表**。平台只给 token 数，把 token 折成钱、按任务类型分摊，是这一层干的（缺价的模型 fail-closed，不按 0 计）。
+3. **一个元节律做体检**：定期算准 backlog、和上次快照比趋势，卡住就报主人——它监督其它节律有没有真在干活，而不是信自述。
+
+### 判"一次自动化到底达成没有"：L0–L4，别信自述
+
+跑了 ≠ 干了 ≠ 干对了。用可观测证据分层，每层的证据都要能独立采到：
+
+| 层 | 含义 | 证据 |
+|---|---|---|
+| L0 | 被唤醒 | 平台账本有 fire |
+| L1 | 命令跑完、拿到清单 | 运行记录有一行 |
+| L2/L3 | 产生写调用、且写到**正确对象** | 有写调用 + 按 recordId 回读命中 |
+| L4 | 目标量指标真的动了 | backlog 净降 / 水位推进（多读取并集当下界，别单次读） |
+
+**大多数"空转"事故都是停在 L1**：命令在跑、runlog 在记，但没有 L3 的写调用、backlog 不动。而运行记录里的自述（"已处理 N 条"）**不是 L3 证据**——只有真实写调用数 + 回读是。判达成度看 L4，不看自述。
+
+---
+
+## 7. 改一行怎么到线上
+
+```text
+改 Agent Definition 或 Skills
+  ↓  git commit → 发布基线分支
+  ↓  dta workspace inspect → dta deploy --dry-run → dta deploy --plan-id … --yes
+  ↓  dta deploy --status --operation-id …
+托管平台上的 Agent
+```
+
+三条运行时纪律：
+
+- **目录存在 ≠ Skill 已加载。** 以部署 Receipt、Definition hash、Skill assignment hash 和加载烟测为准，
+  不能用 git push 或"页面上看得到"来推断已部署。
+- **`inspect → dry-run → apply` 必须连续。** plan 的 scope 从那一次 inspection 冻结；
+  中间插入别的调用会得到"与冻结 plan 不一致"。该门禁在任何远端写入**之前**失败，所以报错后可以安全重试。
+- **最强的验收不是烟测，是功能证据。** 烟测能证明 Skill 被装配、Agent 会应答；
+  它证明不了"这次改动真的改变了行为"。后者只能靠改动本身对应的**数据现象**——
+  比如修了一条补录路径，就去看下一拍有没有真的补出数据来。
+
+**哪些改动需要部署**：Agent Definition 和 Skills 要；节律声明不要（也不能，由 operator 在平台侧执行）；
+仓库开发面（README / AGENTS / docs / 评测配置）不同步。
+
+---
+
+## 8. 它不对劲的时候，按这个顺序查
+
+| 症状 | 先看哪 | 常见真因 |
+|---|---|---|
+| 该发生的事没发生 | 完成判据是不是绑在"那一拍跑了没有"上 | 平台跳过了迟到的 fire |
+| backlog 一直涨 | **拆入口/出口**，别看净值 | 空转、写错行、队头阻塞、产能不足，处方各不相同 |
+| 值班一路报 ✅ 但数据没动 | 完成判据有没有第二处、两处判得一样吗 | 判据分叉，补救路径从没被触发 |
+| 写回"成功"但状态不变 | 回读是不是独立定位了目标 | 写和回读命中同一个错误对象 |
+| 同一条消息发了两遍 | 有没有两条节律落在同一分钟 | 外发类留痕在动作之后，没有锁 |
+| 数字忽然变成 0 | 当成可疑，别当完成 | 后端间歇性返回空集 |
+| 成本对不上账单 | 有没有不产生 issue 的唤醒 | 计量盲区 |
+| 改了但线上没变 | Receipt / hash / 加载烟测 | 根本没部署，或部署了但没验证功能 |
+
+---
+
+## 8.5 这些坑该由平台兜哪些
+
+上面这张排查表里的每一类，都可以问一句「这是不是不该由每个 Agent 各自踩一遍」。把六类真实事故映射到 dta 的原语/CLI闸门/Skill纪律/文档四层的分析，见 [Platform Guardrails](PLATFORM-GUARDRAILS.md)——它也复核了 `dta-people-group-memory` 的四条不变式在静默截断下哪条会失效。
+
+## 9. 一个活的参考实现
+
+本仓库的 Skill 与合同都来自真实生产。目前公开可读的完整案例是「FDE 教练」——
+一个每天被节律唤醒上百次、服务上百名校招生的数字员工。
+它把本文每一节都落成了具体的表、命令和判据，并且**把踩过的坑逐条写在了注释里**：
+
+- 运行方式全景与十条真事故换来的坑：`fde-coach-agent/docs/HOW-IT-WORKS.md`
+- 节律作用域与值班完成判据：该仓库 `agent/skills/fde-heartbeat/SKILL.md`
+
+读本文建立框架，读它建立手感。