@zhushanwen/pi-system-prompt 1.1.6 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt",
-  "version": "1.1.6",
+  "version": "1.3.0",
   "description": "System prompt injection extension for Pi — reads config and appends to system prompt",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/system-prompt.test.ts

@@ -4,13 +4,19 @@
  * 覆盖（替换原 expect(true) 占位，R3 extension-api SUGGESTION #1）：
  * - readJsonIfValid 解析边界：文件缺失 / 畸形 JSON / 顶层 array / 顶层原始值 → 全部收敛 defaults
  * - readSection 字段级防御：section 非对象、enabled 非 true、prompt 非字符串 / 空白 → 不注入
- * - before_agent_start 注入顺序：base → global instructions → append config（indexOf 链锁定，
+ * - capability 段三态锚点（设计 D6）：v1 存量 json（无字段）→ 注入；显式布尔 false → 不注入；
+ *   损坏形态（"enabled": "false" 字符串 / capability 非对象）→ 注入（与 readSection 解析方向相反）
+ * - before_agent_start 注入顺序：base → global instructions → capability → append（indexOf 链锁定，
  *   swap 注入顺序两行的 mutant 会被顺序用例 kill）
  * - -nc / --no-context-files 守卫：global 注入跳过、append 不受影响
  * - global 候选选择：候选序优先、空白内容跳过继续找、目录缺失降级
  * - fail-safe：handler 全程 throw → return undefined + logger.error 可观测；logger 自身抛错的
  *   终极兜底 process.stderr.write；systemPrompt 非法类型的旧 quirk 锚定
  *
+ * 适配约定：capability 默认开（仅显式布尔 false 关闭）。聚焦 append/global 语义的既有用例
+ * 在 config 里显式 "capability":{"enabled":false} 隔离关注点；无法塞字段的用例（畸形 JSON /
+ * 文件缺失）期望值如实更新为含 capability 段。capability 自身行为由专项 describe 锚定。
+ *
  * mock 策略（参照 msg-id-mapper 测试模式）：pi SDK import type 零运行时解析，
  * ExtensionAPI 用结构化桩；node:fs mock 后按路径分流（env 指向假目录，不碰真实文件系统）。
  *
@@ -27,7 +33,13 @@ vi.mock('@zhushanwen/pi-extension-logger', () => ({
 
 import { readFileSync, readdirSync, statSync } from 'node:fs'
 import path from 'node:path'
-import createExtension from '../index'
+import createExtension, {
+  CAPABILITY_FORBIDDEN,
+  CAPABILITY_INLINE_TAG_FAMILIES,
+  CAPABILITY_PRESENTATION_ATTRS,
+  SESSION_ARTIFACTS_DIR_SEGMENT,
+  resolveSessionArtifactsDir,
+} from '../index'
 import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-coding-agent'
 
 vi.mock('node:fs', () => ({
@@ -40,8 +52,13 @@ const DATA_DIR = '/taiji-test/data'
 const GLOBAL_DIR = '/taiji-test/global-agents'
 const CONFIG_PATH = path.join(DATA_DIR, 'system-prompt.json')
 
-/** hook 注册表桩（参照 msg-id-mapper harness 模式） */
-function createHarness(): { beforeAgentStart: (event: BeforeAgentStartEvent) => unknown } {
+/** capability 段 header 锚（文案变更须同步本锚，红 = 提醒评审段文本变化） */
+const CAP_HEADER = '# TaiJi capabilities'
+/** 既有用例隔离关注点用的「capability 显式关闭」config 片段 */
+const CAP_OFF = '"capability": {"enabled": false}'
+
+/** hook 注册表桩（参照 msg-id-mapper harness 模式）——handler 第二参 ctx 透传（路径注入测试用） */
+function createHarness(): { beforeAgentStart: (event: BeforeAgentStartEvent, ctx?: unknown) => unknown } {
   const handlers = new Map<string, (...args: unknown[]) => unknown>()
   const pi = {
     on: (event: string, handler: (...args: unknown[]) => unknown) => {
@@ -50,14 +67,14 @@ function createHarness(): { beforeAgentStart: (event: BeforeAgentStartEvent) =>
   } as unknown as ExtensionAPI
   createExtension(pi)
   return {
-    beforeAgentStart: (event) => handlers.get('before_agent_start')!(event),
+    beforeAgentStart: (event, ctx) => handlers.get('before_agent_start')!(event, ctx),
   }
 }
 
-/** 触发一次 hook 的便捷封装（常规 event：systemPrompt 字符串） */
-function runHook(systemPrompt: string): { systemPrompt?: string } | undefined {
+/** 触发一次 hook 的便捷封装（常规 event：systemPrompt 字符串；ctx 可选） */
+function runHook(systemPrompt: string, ctx?: unknown): { systemPrompt?: string } | undefined {
   const h = createHarness()
-  return h.beforeAgentStart({ type: 'before_agent_start', prompt: 'hi', systemPrompt }) as
+  return h.beforeAgentStart({ type: 'before_agent_start', prompt: 'hi', systemPrompt }, ctx) as
     | { systemPrompt?: string }
     | undefined
 }
@@ -136,62 +153,64 @@ afterEach(() => {
   vi.restoreAllMocks()
 })
 
-describe('readJsonIfValid 解析边界（config 读取 → defaults 收敛）', () => {
-  it('config 文件缺失（ENOENT）→ defaults → 无注入，返回 undefined', () => {
+describe('readJsonIfValid 解析边界（config 读取 → defaults 收敛，capability 默认开）', () => {
+  // 本组 config 均无法塞字段（缺失/畸形/非对象），capability 走默认 true——
+  // defaults 的语义自 schema v2 起含「capability 段注入」，期望如实更新。
+  it('config 文件缺失（ENOENT）→ defaults → 仅注入 capability 段', () => {
     setupFs({ config: new Error("ENOENT: no such file or directory, open '" + CONFIG_PATH + "'") })
-    expect(runHook('base prompt')).toBeUndefined()
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
   })
 
-  it('config 畸形 JSON（parse throw）→ defaults → 无注入', () => {
+  it('config 畸形 JSON（parse throw）→ defaults → 仅注入 capability 段', () => {
     setupFs({ config: '{broken json' })
-    expect(runHook('base prompt')).toBeUndefined()
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
   })
 
-  it('config 顶层 array → isJsonObject 放行 quirk（数组不排除）→ 字段缺省收敛 defaults → 无注入', () => {
+  it('config 顶层 array → isJsonObject 放行 quirk（数组不排除）→ 字段缺省收敛 defaults → 仅 capability 段', () => {
     // R3 复核锚定的行为等价：顶层数组两版实现同走 typeof object 放行路径，无错误数据
     setupFs({ config: '[1, 2]' })
-    expect(runHook('base prompt')).toBeUndefined()
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
   })
 
-  it('config 顶层原始值（number / string / null 字面量）→ null → defaults → 无注入', () => {
+  it('config 顶层原始值（number / string / null 字面量）→ null → defaults → 仅 capability 段', () => {
     for (const bad of ['42', '"a string"', 'null', 'true']) {
       setupFs({ config: bad })
-      expect(runHook('base prompt')).toBeUndefined()
+      expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
     }
   })
 })
 
-describe('readSection 字段级防御（append section）', () => {
+describe('readSection 字段级防御（append section；capability 显式关闭以隔离关注点）', () => {
   it('append section 非对象（null / 字符串）→ {enabled:false, prompt:""} → 不注入', () => {
     for (const section of ['null', '"just text"']) {
-      setupFs({ config: `{"append": ${section}}` })
+      setupFs({ config: `{"append": ${section}, ${CAP_OFF}}` })
       expect(runHook('base prompt')).toBeUndefined()
     }
   })
 
   it('append.enabled 非 true（字符串 "true"）→ 不视为开启 → 不注入', () => {
-    setupFs({ config: '{"append": {"enabled": "true", "prompt": "extra"}}' })
+    setupFs({ config: `{"append": {"enabled": "true", "prompt": "extra"}, ${CAP_OFF}}` })
     expect(runHook('base prompt')).toBeUndefined()
   })
 
   it('append.prompt 非字符串（number）→ 缺省 "" → 不注入', () => {
-    setupFs({ config: '{"append": {"enabled": true, "prompt": 123}}' })
+    setupFs({ config: `{"append": {"enabled": true, "prompt": 123}, ${CAP_OFF}}` })
     expect(runHook('base prompt')).toBeUndefined()
   })
 
   it('append.enabled true 但 prompt 纯空白 → trim 后为空 → 不注入', () => {
-    setupFs({ config: '{"append": {"enabled": true, "prompt": "   \\n\\t "}}' })
+    setupFs({ config: `{"append": {"enabled": true, "prompt": "   \\n\\t "}, ${CAP_OFF}}` })
     expect(runHook('base prompt')).toBeUndefined()
   })
 
   it('append 合法（enabled true + 非空 prompt）→ 注入到 base 之后（\\n\\n 分隔）', () => {
-    setupFs({ config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}' })
+    setupFs({ config: `{"append": {"enabled": true, "prompt": "APPEND-TEXT"}, ${CAP_OFF}}` })
     expect(runHook('base prompt')).toEqual({ systemPrompt: 'base prompt\n\nAPPEND-TEXT' })
   })
 })
 
-describe('before_agent_start 注入顺序（base → global → append）', () => {
-  it('三段齐备 → base 在前、global 段居中、append 文本最后（indexOf 链锁定）', () => {
+describe('before_agent_start 注入顺序（base → global → capability → append）', () => {
+  it('四段齐备 → base 最前、global 居中、capability 段次之、append 最后（indexOf 链锁定）', () => {
     setupFs({
       config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
       globalEntries: ['AGENTS.md'],
@@ -201,35 +220,106 @@ describe('before_agent_start 注入顺序（base → global → append）', () =
     expect(result).toEqual({ systemPrompt: expect.stringContaining('APPEND-TEXT') })
     const prompt = result!.systemPrompt as string
 
-    // 顺序锚点：base 最前 → global header → global 内容 → append 文本最后
+    // 顺序锚点：base → global header → global 内容 → capability 段 → append 文本
     const iBase = prompt.indexOf('BASE-PROMPT')
     const iHeader = prompt.indexOf('# Global instructions')
     const iGlobal = prompt.indexOf('GLOBAL-CONTENT')
+    const iCap = prompt.indexOf(CAP_HEADER)
     const iAppend = prompt.indexOf('APPEND-TEXT')
     expect(iBase).toBeGreaterThanOrEqual(0)
     expect(iHeader).toBeGreaterThan(iBase)
     expect(iGlobal).toBeGreaterThan(iHeader)
-    expect(iAppend).toBeGreaterThan(iGlobal)
+    expect(iCap).toBeGreaterThan(iGlobal)
+    expect(iAppend).toBeGreaterThan(iCap)
     expect(prompt.indexOf('APPEND-TEXT', iAppend + 1)).toBe(-1) // append 恰一次
+    expect(prompt.indexOf(CAP_HEADER, iCap + 1)).toBe(-1) // capability 段恰一次
     // global header 带真实注入路径（可追溯）
     expect(prompt).toContain(path.join(GLOBAL_DIR, 'AGENTS.md'))
   })
 
-  it('global 无候选文件 → 只剩 base + append 两段', () => {
+  it('capability 段文案覆盖四点能力面（HTML 白名单 / 相对图片 / 相对链接双通道 / 远程图片不渲染）', () => {
+    setupFs({ config: '{"append": {"enabled": false, "prompt": ""}}' })
+    const prompt = runHook('BASE-PROMPT')!.systemPrompt as string
+    const capText = prompt.slice(prompt.indexOf(CAP_HEADER))
+    expect(capText).toContain('Inline HTML')
+    expect(capText).toContain('Relative image paths')
+    expect(capText).toContain('Relative links')
+    expect(capText).toContain('not rendered')
+    expect(capText).toContain('backticks')
+  })
+
+  it('capability 关闭（显式布尔 false）→ 段消失，其余段顺序不变', () => {
+    setupFs({
+      config: `{"append": {"enabled": true, "prompt": "APPEND-TEXT"}, ${CAP_OFF}}`,
+      globalEntries: ['AGENTS.md'],
+      globalFiles: { 'AGENTS.md': 'GLOBAL-CONTENT' },
+    })
+    const prompt = runHook('BASE-PROMPT')!.systemPrompt as string
+    expect(prompt).not.toContain(CAP_HEADER)
+    // 三段顺序保持 base → global → append（capability 摘除不动既有链路）
+    const iBase = prompt.indexOf('BASE-PROMPT')
+    const iGlobal = prompt.indexOf('GLOBAL-CONTENT')
+    const iAppend = prompt.indexOf('APPEND-TEXT')
+    expect(iBase).toBeGreaterThanOrEqual(0)
+    expect(iGlobal).toBeGreaterThan(iBase)
+    expect(iAppend).toBeGreaterThan(iGlobal)
+  })
+
+  it('global 无候选文件 → 只剩 base + capability + append 三段', () => {
     setupFs({
       config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
       globalEntries: [],
     })
     const result = runHook('BASE-PROMPT')
-    expect(result).toEqual({ systemPrompt: 'BASE-PROMPT\n\nAPPEND-TEXT' })
-    expect(result!.systemPrompt).not.toContain('# Global instructions')
+    const prompt = result!.systemPrompt as string
+    expect(prompt).not.toContain('# Global instructions')
+    expect(prompt).toContain(CAP_HEADER)
+    expect(prompt).toContain('APPEND-TEXT')
+    expect(prompt.indexOf(CAP_HEADER)).toBeGreaterThan(prompt.indexOf('BASE-PROMPT'))
+    expect(prompt.indexOf('APPEND-TEXT')).toBeGreaterThan(prompt.indexOf(CAP_HEADER))
+  })
+})
+
+describe('capability 段三态锚点（设计 D6：仅显式布尔 false 关闭，与 readSection 方向相反）', () => {
+  it('v1 存量 json（无 capability 字段）→ 默认开 → 注入', () => {
+    setupFs({ config: '{"version": 1, "replace": {"enabled": false, "prompt": ""}, "append": {"enabled": false, "prompt": ""}}' })
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+  })
+
+  it('config 文件不存在 → 同 v1 语义 → 注入', () => {
+    setupFs()
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+  })
+
+  it('显式 enabled: false（布尔）→ 关闭 → 不注入', () => {
+    setupFs({ config: `{"append": {"enabled": false, "prompt": ""}, ${CAP_OFF}}` })
+    expect(runHook('base prompt')).toBeUndefined()
+  })
+
+  it('显式 enabled: true → 注入', () => {
+    setupFs({ config: '{"append": {"enabled": false, "prompt": ""}, "capability": {"enabled": true}}' })
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+  })
+
+  it('损坏形态：enabled 为字符串 "false"（非布尔）→ 不视为关闭 → 注入', () => {
+    setupFs({ config: '{"append": {"enabled": false, "prompt": ""}, "capability": {"enabled": "false"}}' })
+    expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+  })
+
+  it('损坏形态：capability 字段非对象（字符串 / null / 数组）→ 注入', () => {
+    for (const bad of ['"off"', 'null', '[1]']) {
+      setupFs({ config: `{"append": {"enabled": false, "prompt": ""}, "capability": ${bad}}` })
+      expect(runHook('base prompt')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+    }
   })
 })
 
 describe('-nc / --no-context-files 守卫（contextFilesDisabled）', () => {
+  // capability 与守卫正交（内置段不受 --no-context-files 影响，该旗标只管上下文文件
+  // 发现），用例显式关 capability 隔离守卫语义。
   it('argv 含 --no-context-files → global 不注入，append 仍生效（用户显式退出不得溜回来）', () => {
     setupFs({
-      config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
+      config: `{"append": {"enabled": true, "prompt": "APPEND-TEXT"}, ${CAP_OFF}}`,
       globalEntries: ['AGENTS.md'],
       globalFiles: { 'AGENTS.md': 'GLOBAL-CONTENT' },
     })
@@ -239,9 +329,9 @@ describe('-nc / --no-context-files 守卫（contextFilesDisabled）', () => {
     expect(readdirSync).not.toHaveBeenCalled()
   })
 
-  it('argv 含 -nc 短形式 → 同样跳过 global 注入（与 argv-mirror 两种形式一致）', () => {
+  it('argv 含 -nc 短形式 → 同样跳过 global 注入（pi CLI 等价短形式，守卫两种形式都命中）', () => {
     setupFs({
-      config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}',
+      config: `{"append": {"enabled": true, "prompt": "APPEND-TEXT"}, ${CAP_OFF}}`,
       globalEntries: ['AGENTS.md'],
       globalFiles: { 'AGENTS.md': 'GLOBAL-CONTENT' },
     })
@@ -251,30 +341,32 @@ describe('-nc / --no-context-files 守卫（contextFilesDisabled）', () => {
 })
 
 describe('global 候选文件选择（readGlobalAgentsFile）', () => {
-  it('候选序优先：AGENTS.MD 与 CLAUDE.md 并存 → AGENTS.MD 胜（候选列表顺序的第一个存在者）', () => {
+  it('候选序优先：AGENTS.md 与 AGENTS.MD 并存 → AGENTS.md 胜（候选列表顺序的第一个存在者）', () => {
     setupFs({
-      globalEntries: ['AGENTS.MD', 'CLAUDE.md'],
-      globalFiles: { 'AGENTS.MD': 'FROM-AGENTS-UPPER', 'CLAUDE.md': 'FROM-CLAUDE' },
+      globalEntries: ['AGENTS.md', 'AGENTS.MD'],
+      globalFiles: { 'AGENTS.md': 'FROM-LOWER', 'AGENTS.MD': 'FROM-UPPER' },
     })
     const result = runHook('BASE-PROMPT')
-    expect(result!.systemPrompt).toContain('FROM-AGENTS-UPPER')
-    expect(result!.systemPrompt).not.toContain('FROM-CLAUDE')
-    expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'AGENTS.MD'))
+    expect(result!.systemPrompt).toContain('FROM-LOWER')
+    expect(result!.systemPrompt).not.toContain('FROM-UPPER')
+    expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'AGENTS.md'))
   })
 
-  it('首候选内容空白 → 跳过继续找下一候选（AGENTS.md 空白 + CLAUDE.md 有内容 → 注入 CLAUDE.md）', () => {
+  it('首候选内容空白 → 跳过继续找下一候选（AGENTS.md 空白 + AGENTS.MD 有内容 → 注入 AGENTS.MD）', () => {
     setupFs({
-      globalEntries: ['AGENTS.md', 'CLAUDE.md'],
-      globalFiles: { 'AGENTS.md': '   \n\t', 'CLAUDE.md': 'FROM-CLAUDE' },
+      globalEntries: ['AGENTS.md', 'AGENTS.MD'],
+      globalFiles: { 'AGENTS.md': '   \n\t', 'AGENTS.MD': 'FROM-UPPER' },
     })
     const result = runHook('BASE-PROMPT')
-    expect(result!.systemPrompt).toContain('FROM-CLAUDE')
-    expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'CLAUDE.md'))
+    expect(result!.systemPrompt).toContain('FROM-UPPER')
+    expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'AGENTS.MD'))
   })
 
-  it('global 目录不存在（readdirSync throw）→ 降级 null：不注入、不抛错', () => {
+  it('global 目录不存在（readdirSync throw）→ 降级 null：global 不注入、不抛错（capability 默认段仍在）', () => {
     setupFs({ globalEntries: new Error('ENOENT: no such directory') })
-    expect(runHook('BASE-PROMPT')).toBeUndefined()
+    const result = runHook('BASE-PROMPT')
+    expect(result).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+    expect(result!.systemPrompt).not.toContain('# Global instructions')
   })
 })
 
@@ -311,20 +403,26 @@ describe('fail-safe（外层 catch return undefined，永不阻断 agent loop）
     )
   })
 
-  it('systemPrompt 非法类型（undefined）且无注入 → 旧 quirk 锚定：返回 {systemPrompt:""} 而非 undefined', () => {
+  it('systemPrompt 非法类型（undefined）且无 append → 旧 quirk 锚定：返回仅含 capability 段的结果而非 undefined', () => {
     // R3 复核锚定的返回值守卫 quirk（index.ts newPrompt === event.systemPrompt 比较）：
-    // base 收敛 ''，'' !== undefined → 返回 {systemPrompt: ''}。与重构前行为一致（非回归）。
+    // base 收敛 ''，capability 默认开 → newPrompt 非空且 !== undefined → 必然返回对象。
+    // 与重构前行为一致（非回归）：quirk 在「有注入时必然返回对象」，schema v2 后 capability
+    // 默认开使该形态成为常态。
     const h = createHarness()
     const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
-    expect(h.beforeAgentStart(event)).toEqual({ systemPrompt: '' })
+    expect(h.beforeAgentStart(event)).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
   })
 
-  it('systemPrompt 非法类型（undefined）但有 append 注入 → newPrompt = 空串 base + 分隔符 + append', () => {
+  it('systemPrompt 非法类型（undefined）但有 append 注入 → 空串 base + capability 段 + append 依序拼接', () => {
     setupFs({ config: '{"append": {"enabled": true, "prompt": "APPEND-TEXT"}}' })
     const h = createHarness()
     const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
-    // base 收敛 ''，拼接形态固定为 '' + '\n\n' + append（分隔符保留，与合法 base 一致）
-    expect(h.beforeAgentStart(event)).toEqual({ systemPrompt: '\n\nAPPEND-TEXT' })
+    // base 收敛 ''，拼接形态固定为 '' + '\n\n' + capability + '\n\n' + append（分隔符保留，与合法 base 一致）
+    const result = h.beforeAgentStart(event) as { systemPrompt: string }
+    expect(result.systemPrompt).toContain(CAP_HEADER)
+    expect(result.systemPrompt).toContain('APPEND-TEXT')
+    expect(result.systemPrompt.indexOf('APPEND-TEXT')).toBeGreaterThan(result.systemPrompt.indexOf(CAP_HEADER))
+    expect(result.systemPrompt.startsWith('\n\n')).toBe(true)
   })
 })
 
@@ -343,17 +441,187 @@ describe('cachedReadFileSync（mtime 级内容缓存，KV-cache 稳定性改造
   })
 
   it('文件改写（mtime 变）后下一轮 hook 读到新内容（变更即生效语义保留）', () => {
-    setupFs({ config: '{"append": {"enabled": true, "prompt": "P1"}}' })
+    // CAP_OFF：本条锚精确串「base + P1」，capability 开启会让期望值带上整段常量文案，
+    // 显式关闭以保持断言可读；capability 的变更即生效由 readConfig 共用路径保证。
+    setupFs({ config: `{"append": {"enabled": true, "prompt": "P1"}, ${CAP_OFF}}` })
     expect(runHook('base')).toEqual({ systemPrompt: 'base\n\nP1' })
     // 模拟用户改写 append.prompt（setupFs 递增 mtime 纪元）
-    setupFs({ config: '{"append": {"enabled": true, "prompt": "P2"}}' })
+    setupFs({ config: `{"append": {"enabled": true, "prompt": "P2"}, ${CAP_OFF}}` })
     expect(runHook('base')).toEqual({ systemPrompt: 'base\n\nP2' })
   })
 
-  it('文件删除（stat throw）后缓存驱逐，注入降级为无 append', () => {
-    setupFs({ config: '{"append": {"enabled": true, "prompt": "P1"}}' })
+  it('文件删除（stat throw）后缓存驱逐，append 注入降级消失，capability 回默认开', () => {
+    setupFs({ config: `{"append": {"enabled": true, "prompt": "P1"}, ${CAP_OFF}}` })
     expect(runHook('base')).toEqual({ systemPrompt: 'base\n\nP1' })
-    setupFs() // config 恢复默认 ENOENT
-    expect(runHook('base')).toBeUndefined()
+    setupFs() // config 恢复默认 ENOENT → defaults：append 无、capability 默认开
+    expect(runHook('base')).toEqual({ systemPrompt: expect.stringContaining(CAP_HEADER) })
+  })
+})
+
+// ── 能力段 ①② 渲染锁定 + 产物目录镜像常量（chat-html-support u1-prompt）──────────
+
+/** 能力段清单区的边界标签（文案与源码 renderCapabilitySection 渲染的 capability 段同字面量）。 */
+const POS_TAGS_LABEL = 'You may use these tags: '
+const POS_ATTRS_LABEL = 'Presentational attributes allowed: '
+const FORBIDDEN_TAGS_LABEL = 'Do not use these tags (they are stripped before rendering): '
+const FORBIDDEN_ATTRS_LABEL = 'Do not use these attributes (they are stripped and have no effect): '
+
+/** 从能力段截取 startLabel..endLabel 之间的逗号分隔清单。缺失边界 → 断言失败（防静默跳过）。 */
+function parseListRegion(section: string, startLabel: string, endLabel: string): string[] {
+  const i = section.indexOf(startLabel)
+  expect(i, `能力段缺少清单标签: ${startLabel}`).toBeGreaterThanOrEqual(0)
+  const start = i + startLabel.length
+  const j = section.indexOf(endLabel, start)
+  expect(j, `能力段缺少清单结束标签: ${endLabel}`).toBeGreaterThan(start)
+  return section.slice(start, j).split(', ').map((s) => s.trim())
+}
+
+/** 集合比较用：去重 + 稳定排序（渲染顺序不参与断言，成员集合才是契约）。 */
+const asSet = (xs: readonly string[]): string[] => [...new Set(xs)].sort()
+
+/** 触发一次 hook 并返回 capability 段全文（默认开关开、无 append / global）。 */
+function capabilitySectionText(): string {
+  setupFs({ config: `{"append": {"enabled": false, "prompt": ""}, "capability": {"enabled": true}}` })
+  const prompt = runHook('BASE-PROMPT')!.systemPrompt as string
+  const i = prompt.indexOf(CAP_HEADER)
+  expect(i).toBeGreaterThanOrEqual(0)
+  return prompt.slice(i)
+}
+
+describe('capability 段 ①② 渲染锁定（文案 = 常量渲染产物，手写散文旁路即红）', () => {
+  it('正面清单逐项等于常量集合（含全部成员、无旁路成员、无重复）', () => {
+    const section = capabilitySectionText()
+    const tags = parseListRegion(section, POS_TAGS_LABEL, '. ' + POS_ATTRS_LABEL)
+    const attrs = parseListRegion(section, POS_ATTRS_LABEL, '.\n')
+    const allTags = Object.values(CAPABILITY_INLINE_TAG_FAMILIES).flat()
+
+    // 无重复（渲染旁路/手写追加会引入重复项）
+    expect(tags.length).toBe(new Set(tags).size)
+    expect(attrs.length).toBe(new Set(attrs).size)
+    // 集合逐项相等：缺成员 = 文案旁路漏写；多成员 = 手写散文多出
+    expect(asSet(tags)).toEqual(asSet(allTags))
+    expect(asSet(attrs)).toEqual(asSet(CAPABILITY_PRESENTATION_ATTRS))
+  })
+
+  it('负面清单逐项等于常量集合（构造性剥除的标签与属性）', () => {
+    const section = capabilitySectionText()
+    const forbiddenTags = parseListRegion(section, FORBIDDEN_TAGS_LABEL, '. ' + FORBIDDEN_ATTRS_LABEL)
+    const forbiddenAttrs = parseListRegion(section, FORBIDDEN_ATTRS_LABEL, '.\n')
+
+    expect(asSet(forbiddenTags)).toEqual(asSet(CAPABILITY_FORBIDDEN.tags))
+    expect(asSet(forbiddenAttrs)).toEqual(asSet(CAPABILITY_FORBIDDEN.attributes))
+  })
+
+  it('capability.enabled=false → 整段（含 ①② 清单）不注入', () => {
+    setupFs({ config: `{"append": {"enabled": false, "prompt": ""}, ${CAP_OFF}}` })
+    expect(runHook('BASE-PROMPT')).toBeUndefined()
+  })
+
+  it('清单常量成员与渲染管线白名单同域（包内自锚：52 标签 / 76 属性）', () => {
+    expect(Object.values(CAPABILITY_INLINE_TAG_FAMILIES).flat()).toHaveLength(52)
+    expect(CAPABILITY_PRESENTATION_ATTRS).toHaveLength(76)
+    // 族归类不重复：每个标签恰出现一次
+    const all = Object.values(CAPABILITY_INLINE_TAG_FAMILIES).flat()
+    expect(all.length).toBe(new Set(all).size)
+    // 禁用清单与正面清单不相交（构造性剥除语义）
+    const positive = new Set(all)
+    for (const tag of CAPABILITY_FORBIDDEN.tags) expect(positive.has(tag)).toBe(false)
+  })
+})
+
+describe('产物目录镜像常量与推导 helper（设计 D1/D7，供 u-artifacts 公式对拍消费）', () => {
+  it('段名字面量为 artifacts', () => {
+    expect(SESSION_ARTIFACTS_DIR_SEGMENT).toBe('artifacts')
+  })
+
+  it('合法 pi sid → <dataDir>/artifacts/<sessionId>', () => {
+    expect(resolveSessionArtifactsDir('0198ab12-cdef-7000-8000-1234567890ab')).toBe(
+      path.join(DATA_DIR, 'artifacts', '0198ab12-cdef-7000-8000-1234567890ab'),
+    )
+    // 允许 `.` 与 `_`（与 isPiSessionId 同域）
+    expect(resolveSessionArtifactsDir('a.b-c_d')).toBe(path.join(DATA_DIR, 'artifacts', 'a.b-c_d'))
+  })
+
+  it('非法 sessionId（含冒号 / 空串 / 首尾非字母数字）→ throw（防路径穿越）', () => {
+    for (const bad of ['btw:x', '', '_leading', 'trailing-', 'a/b', '..', 'a b']) {
+      expect(() => resolveSessionArtifactsDir(bad)).toThrow(/invalid sessionId/)
+    }
+  })
+
+  it('resolveDataDir 回退（无 TAIJI_AGENT_DATA_DIR 时取 PI_CODING_AGENT_DIR 上级）', () => {
+    delete process.env.TAIJI_AGENT_DATA_DIR
+    process.env.PI_CODING_AGENT_DIR = path.join('/tmp/fallback-data', 'agent')
+    expect(resolveSessionArtifactsDir('abc')).toBe(path.join('/tmp/fallback-data', 'artifacts', 'abc'))
+  })
+})
+
+// ── 能力段 ③④ 与产物目录路径注入（chat-html-support §6.1 D1 / §5.1 样例）────────────
+
+/** 触发一次 hook 并返回 capability 段全文（capability 开、无 append / global；ctx 可选）。 */
+function capabilityTextWithCtx(ctx?: unknown): string {
+  setupFs({ config: `{"append": {"enabled": false, "prompt": ""}, "capability": {"enabled": true}}` })
+  const prompt = runHook('BASE-PROMPT', ctx)!.systemPrompt as string
+  const i = prompt.indexOf(CAP_HEADER)
+  expect(i).toBeGreaterThanOrEqual(0)
+  return prompt.slice(i)
+}
+
+/** ctx 桩：sessionManager.getSessionId 返回给定值（u-foundation 核实的 pi ExtensionContext 形状） */
+function ctxWithSessionId(getSessionId: () => string): unknown {
+  return { sessionManager: { getSessionId } }
+}
+
+describe('capability 段 ③④（HTML 交付约定 + 预览约束）与产物目录路径注入', () => {
+  const SID = '0198ab12-cdef-7000-8000-1234567890ab'
+
+  it('ctx 会话 id 在 → ③ 段含产物目录绝对路径（与会话 id 匹配）', () => {
+    const text = capabilityTextWithCtx(ctxWithSessionId(() => SID))
+    // 路径 = <dataDir>/artifacts/<sid>（与 shared getSessionArtifactsDir 同公式）
+    expect(text).toContain(resolveSessionArtifactsDir(SID))
+    expect(text).toContain(path.join(DATA_DIR, 'artifacts', SID))
+    // ③ 段交付约定与 ④ 段预览约束齐备
+    expect(text).toContain('info string is html-preview')
+    expect(text).toContain("that file's absolute path")
+    expect(text).toContain('update the file in place on later changes')
+    expect(text).toContain('recycled automatically once stale')
+    expect(text).toContain('Previewed HTML runs sandboxed with no network access')
+    expect(text).toContain('CDN links will not load')
+  })
+
+  it('会话 id 缺失（无 ctx / getSessionId 空串 / sessionManager 缺失）→ 该处退化且其余文案完整', () => {
+    const cases: (unknown | undefined)[] = [
+      undefined,
+      ctxWithSessionId(() => ''),
+      {},
+    ]
+    for (const ctx of cases) {
+      const text = capabilityTextWithCtx(ctx)
+      expect(text).toContain('session artifacts directory (unavailable this turn)')
+      // 其余 ③④ 文案完整（只路径处退化）
+      expect(text).toContain('info string is html-preview')
+      expect(text).toContain('regenerate on reference failure instead of assuming persistence')
+      expect(text).toContain('scripts/styles/images may be inline or reference local files')
+      expect(text).toContain('fonts must be inlined as data: URIs')
+      expect(text).toContain('blocked by the browser CORS policy')
+      expect(text).toContain('CDN links will not load')
+      // 不出现半截/伪造路径
+      expect(text).not.toContain(path.join(DATA_DIR, 'artifacts'))
+    }
+  })
+
+  it('getSessionId 抛错 / 非法 id（含冒号 virtual id）→ 退化不阻塞，其余文案完整', () => {
+    const throwing = ctxWithSessionId(() => { throw new Error('no session context') })
+    const virtualId = ctxWithSessionId(() => 'btw:0198ab12-cdef')
+    for (const ctx of [throwing, virtualId]) {
+      const text = capabilityTextWithCtx(ctx)
+      expect(text).toContain('(unavailable this turn)')
+      expect(text).toContain('info string is html-preview')
+      expect(text).not.toContain(path.join(DATA_DIR, 'artifacts'))
+    }
+  })
+
+  it('capability.enabled=false → ③④ 同整段一起不注入', () => {
+    setupFs({ config: `{"append": {"enabled": false, "prompt": ""}, ${CAP_OFF}}` })
+    expect(runHook('BASE-PROMPT', ctxWithSessionId(() => SID))).toBeUndefined()
   })
 })

package/src/index.ts

@@ -4,10 +4,14 @@
  * Registers a `before_agent_start` hook that:
  *  1. Reads <dataDir>/system-prompt.json every turn (mtime-cached, see
  *     `cachedReadFileSync`).
- *  2. When `append.enabled === true` and `append.prompt` is non-blank,
+ *  2. Appends the fixed taiji capability section unless explicitly disabled
+ *     (`capability.enabled === false` — anything else, including a missing
+ *     field, keeps it ON; deliberate inversion of the readSection fail-safe
+ *     direction, see `readCapabilityEnabled`).
+ *  3. When `append.enabled === true` and `append.prompt` is non-blank,
  *     appends the user's text to the event's systemPrompt.
- *  3. Reads the global instructions file `~/.agents/AGENTS.md` (candidates
- *     AGENTS.md / AGENTS.MD / CLAUDE.md / CLAUDE.MD) every turn and appends it
+ *  4. Reads the global instructions file `~/.agents/AGENTS.md` (candidates
+ *     AGENTS.md / AGENTS.MD, exact case match) every turn and appends it
  *     under a labeled header. Modeled on pi's native `loadContextFileFromDir`
  *     but deliberately narrower: pi 0.84.4 also probes `AGENTS.override.md`
  *     and applies its candidate list to project dirs, whereas this list only
@@ -17,8 +21,9 @@
  *     context-file opt-out). `TAIJI_GLOBAL_AGENTS_DIR` overrides the global
  *     directory (test hook / escape hatch).
  *
- * Injection order per turn: base prompt → global instructions → append config
- * (the explicitly configured text wins last).
+ * Injection order per turn: base prompt → global instructions → taiji
+ * capability section → append config (the explicitly configured text wins
+ * last).
  *
  * Fail-safe: any error in the handler is swallowed and `undefined` is returned
  * so the agent loop is never blocked.
@@ -27,7 +32,7 @@
 import path from 'node:path'
 import { homedir } from 'node:os'
 import { readFileSync, readdirSync, statSync } from 'node:fs'
-import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, BeforeAgentStartEvent, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { getLogger } from '@zhushanwen/pi-extension-logger'
 
 const logger = getLogger('taiji-system-prompt-extension')
@@ -61,12 +66,122 @@ function cachedReadFileSync(filePath: string): string | null {
 
 /**
  * Global instruction candidates. Modeled on pi's native loadContextFileFromDir
- * but deliberately not a strict mirror: pi 0.84.4 probes
- * ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]
- * against project dirs, while these candidates apply only to the global agents
- * directory and intentionally exclude AGENTS.override.md.
+ * but deliberately not a strict mirror: pi 0.84.4 probes its own candidate
+ * list (including AGENTS.override.md) against project dirs, while these
+ * candidates apply only to the global agents directory, intentionally exclude
+ * AGENTS.override.md, and recognize only AGENTS.md case variants.
  */
-const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
+const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD']
+
+/**
+ * 对话流渲染管线的 HTML 能力边界（chat-html-support 设计 D1 ①②）：机器可读的结构化
+ * 常量，能力段文案由这些常量渲染——禁止把清单写成散文旁路（成员集合可被
+ * `scripts/check-capability-allowlist-sync.mjs` 与渲染管线白名单对拍，零散文解析）。
+ *
+ * 成员来源 = `packages/renderer/src/composables/logic/markdown-sanitize.ts` 的
+ * `ALLOWED_TAGS` 实际字面量（52 项，GitHub 风格白名单翻译，按族归类，每项恰一次）。
+ * 与渲染白名单的任一方向漂移（清单多出未放行成员 / 白名单新增未入清单）由对拍机检
+ * 红灯拦住，pre-commit 按路径触发。
+ */
+export const CAPABILITY_INLINE_TAG_FAMILIES: Readonly<Record<string, readonly string[]>> = {
+  headings: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+  text: ['p', 'br', 'span', 'div', 'section', 'blockquote', 'pre', 'hr'],
+  inline: [
+    'a', 'b', 'i', 'em', 'strong', 's', 'strike', 'del', 'ins',
+    'code', 'kbd', 'samp', 'tt', 'var', 'sub', 'sup', 'q',
+  ],
+  lists: ['ul', 'ol', 'li', 'dl', 'dt', 'dd'],
+  table: ['table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td'],
+  media: ['img', 'picture', 'source'],
+  annotation: ['ruby', 'rt', 'rp'],
+  details: ['details', 'summary'],
+}
+
+/**
+ * 可用呈现属性（设计 D1 ①）：成员 = `markdown-sanitize.ts` 的 `ALLOWED_ATTR` 实际
+ * 字面量（defaultSchema 全局 '*' 表 + 按标签项；class 与任意 data-* 不翻译）。
+ */
+export const CAPABILITY_PRESENTATION_ATTRS: readonly string[] = [
+  // defaultSchema 全局 '*' 表
+  'abbr', 'accept', 'accept-charset', 'accesskey', 'action', 'align', 'alt', 'axis',
+  'border', 'cellpadding', 'cellspacing', 'char', 'charoff', 'charset', 'checked',
+  'clear', 'colspan', 'color', 'cols', 'compact', 'coords', 'datetime', 'dir',
+  'disabled', 'enctype', 'frame', 'hspace', 'headers', 'height', 'hreflang', 'for',
+  'id', 'ismap', 'itemprop', 'label', 'lang', 'maxlength', 'media', 'method',
+  'multiple', 'name', 'nohref', 'noshade', 'nowrap', 'open', 'prompt', 'readonly',
+  'rel', 'rev', 'rowspan', 'rows', 'rules', 'scope', 'selected', 'shape', 'size',
+  'span', 'start', 'summary', 'tabindex', 'target', 'title', 'usemap', 'valign',
+  'value', 'width',
+  // defaultSchema 按标签项
+  'cite', 'itemscope', 'itemtype', 'longdesc', 'src', 'srcset', 'href',
+  'aria-describedby', 'aria-label', 'aria-labelledby',
+]
+
+/**
+ * 禁用清单（设计 D1 ②）：净化层构造性剥除的标签与属性。
+ * - 标签 = 不在 `ALLOWED_TAGS` 的 script / style / link / iframe / form / input /
+ *   button / svg；
+ * - 属性 = class / style 与通配 data-* / on*（净化层 `ALLOW_DATA_ATTR: false` 构造性
+ *   全剥 data-*，on* 事件处理器同理不存活）。
+ * 通配项以 `*` 结尾，对拍机检按前缀比对剥除语义。
+ */
+export const CAPABILITY_FORBIDDEN: {
+  readonly tags: readonly string[]
+  readonly attributes: readonly string[]
+} = {
+  tags: ['button', 'form', 'iframe', 'input', 'link', 'script', 'style', 'svg'],
+  attributes: ['class', 'style', 'data-*', 'on*'],
+}
+
+/**
+ * 能力段 ①② 的清单渲染（文案由常量渲染，禁手写散文旁路）。渲染顺序 = 常量声明顺序，
+ * 包内单测按「解析出的清单集合 === 常量集合」逐项锁定（含常量集合全部成员、无旁路成员
+ * ——防对拍机检空转）。
+ */
+function renderCapabilityLists(): {
+  tags: string
+  attrs: string
+  forbiddenTags: string
+  forbiddenAttrs: string
+} {
+  return {
+    tags: Object.values(CAPABILITY_INLINE_TAG_FAMILIES).flat().join(', '),
+    attrs: CAPABILITY_PRESENTATION_ATTRS.join(', '),
+    forbiddenTags: CAPABILITY_FORBIDDEN.tags.join(', '),
+    forbiddenAttrs: CAPABILITY_FORBIDDEN.attributes.join(', '),
+  }
+}
+
+const CAPABILITY_LISTS = renderCapabilityLists()
+
+/**
+ * taiji capability 固定注入段（chat-html-support 设计 D1）：告知 AI 本渲染器的能力面，让新会话
+ * 无需用户手动教。常量放扩展源码内（版本化随 feature 走，非用户配置——用户只持有 on/off 开关，
+ * 不持有文案本身）。文案英文，与 pi system prompt 语言一致。
+ *
+ * M0 = ①②（inline HTML 正面清单 + 负面清单，文案由 CAPABILITY_* 常量渲染）；
+ * M1 = ③④（HTML 产物交付约定 + 预览约束告知，本函数追加）。其余三点 = 相对图片 cwd 解析 /
+ * 相对链接 cwd 解析（与反引号白名单路径自动链接化同基准、校验面差异如实）/ 远程图片不渲染
+ * + 反引号规约。
+ *
+ * @param artifactsDir 会话产物目录绝对路径（handler 每 turn 经 ctx 推导后拼入 ③ 段）；
+ *   null = 会话 id 缺失 / 不可解析 → 该处退化为 SESSION_ARTIFACTS_DIR_UNAVAILABLE，
+ *   其余文案完整（设计 D1「该行退化」）。
+ */
+function renderCapabilitySection(artifactsDir: string | null): string {
+  const artifactsRef = artifactsDir ?? SESSION_ARTIFACTS_DIR_UNAVAILABLE
+  return `# TaiJi capabilities
+
+How TaiJi renders your markdown responses:
+
+- Inline HTML is rendered with a GitHub-grade allowlist; anything outside it is stripped before rendering. You may use these tags: ${CAPABILITY_LISTS.tags}. Presentational attributes allowed: ${CAPABILITY_LISTS.attrs}.
+- Do not use these tags (they are stripped before rendering): ${CAPABILITY_LISTS.forbiddenTags}. Do not use these attributes (they are stripped and have no effect): ${CAPABILITY_LISTS.forbiddenAttrs}.
+- For anything larger than a small fragment (reports, charts, interactive pages): write the HTML file into the session artifacts directory ${artifactsRef}${artifactsDir ? ' (given above each turn)' : ''}, then reference it with a fenced block whose info string is html-preview and whose content is that file's absolute path. Never paste the full HTML into your reply after writing the file — update the file in place on later changes. Artifacts are recycled automatically once stale (retention policy) — regenerate on reference failure instead of assuming persistence.
+- Previewed HTML runs sandboxed with no network access: scripts/styles/images may be inline or reference local files by relative path next to the HTML file; fonts must be inlined as data: URIs (relative-path font files are blocked by the browser CORS policy for the opaque-origin preview). CDN links will not load.
+- Relative image paths (e.g. ![](docs/assets/img.png)) are resolved against the session working directory and displayed.
+- Relative links (e.g. [plan](docs/plan.md)) use the same session working directory; clicking one opens the target file inside the app. Backtick file paths that TaiJi auto-links share the same cwd base. Difference in guarantees: auto-linked backtick paths are checked to exist, relative links may be dead — when citing a file you know exists, backticks are the safer form.
+- Remote http(s) images are not rendered; reference a local file path instead. Always use backticks for inline code and type names in prose (bare angle-bracket names like Promise<void> are stripped).`
+}
 
 /**
  * Resolve the data directory from the environment.
@@ -95,6 +210,64 @@ function resolveDataDir(): string {
   return path.resolve(process.env.PI_CODING_AGENT_DIR ?? '', '..')
 }
 
+/**
+ * 会话产物目录镜像常量（设计 D1/D7）：`<dataDir>/artifacts/<sessionId>/`。
+ *
+ * shared 侧单点声明 = `packages/shared/src/paths.ts` 的 `getSessionArtifactsDir`；本包
+ * 不 import `@taiji/shared`（① 包边界——extensions 包全体不依赖 @taiji/shared；② 运行时
+ * 门禁——shared `getDataDir()` 对「非打包进程持有 ~/.taiji 树值」直接 throw（C-proc-26），
+ * 而打包态 pi 进程恰构成该组合（C-proc-09 剥了 TAIJI_AGENT_PACKAGED），误用会让打包态
+ * capability 段整段静默消失）。故以同公式镜像推导，两侧字面量一致性由 u-artifacts 的
+ * 源文件对拍机检守护（§11 检查点 8）。
+ */
+export const SESSION_ARTIFACTS_DIR_SEGMENT = 'artifacts'
+
+/**
+ * 会话产物目录绝对路径（镜像 shared `getSessionArtifactsDir` 公式）。
+ *
+ * sessionId 校验与 pi `assertValidSessionId` / runtime `isPiSessionId` 同域：首尾字母
+ * 数字，中间允许 `[A-Za-z0-9._-]`（允许 `.` / `_`，禁 `:`）——不用 `getImageCacheDir`
+ * 的窄集 `/^[A-Za-z0-9_-]+$/`（合法含 `.` 的 pi sid 会被窄集误拒）。非法 sessionId
+ * 直接 throw（防路径穿越）。
+ *
+ * @param sessionId 会话 id（子目录分区，须与 `isPiSessionId` 同域）
+ * @throws Error 当 sessionId 含路径分隔符、冒号、空串或首尾非字母数字
+ */
+export function resolveSessionArtifactsDir(sessionId: string): string {
+  // 校验与 pi-paths.ts 的 isPiSessionId 同域（字面量与 shared getSessionArtifactsDir 一致）
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(sessionId)) {
+    throw new Error(`invalid sessionId (path traversal blocked): ${sessionId}`)
+  }
+  return path.join(resolveDataDir(), SESSION_ARTIFACTS_DIR_SEGMENT, sessionId)
+}
+
+/**
+ * 产物目录不可用时的占位文案（会话 id 缺失 / 不可解析，设计 D1）：拼入能力段 ③ 段，
+ * 退化只发生在该处，其余文案完整。
+ */
+const SESSION_ARTIFACTS_DIR_UNAVAILABLE = '(unavailable this turn)'
+
+/**
+ * 从 handler 第二参 ctx 推导会话产物目录绝对路径（设计 D1 路径注入）：
+ * `ctx.sessionManager.getSessionId()` + 包内镜像推导（resolveDataDir + 段名常量，
+ * 不经 @taiji/shared——包边界与 C-proc-26/C-proc-09 门禁组合，见 D1）。
+ *
+ * 会话 id 缺失（无 ctx / getSessionId 返回空）/ 非法（resolveSessionArtifactsDir throw，
+ * 如 btw 虚拟 id 含冒号）/ getSessionId 抛错 → null，调用方按退化形态渲染。
+ */
+function resolveArtifactsDirFromCtx(ctx?: ExtensionContext): string | null {
+  try {
+    const manager = ctx?.sessionManager
+    const sid = manager ? manager.getSessionId() : ''
+    if (!sid) return null
+    return resolveSessionArtifactsDir(sid)
+  } catch (err) {
+    // best-effort：本 turn 路径缺失 → 退化形态（绝不把异常漏给 agent loop）
+    logger.debug('session artifacts dir unavailable this turn', { detail: String(err) })
+    return null
+  }
+}
+
 /**
  * Resolve the global agents directory.
  *
@@ -152,30 +325,42 @@ function readGlobalAgentsFile(): { path: string; content: string } | null {
 /**
  * Read & parse the config file. Missing / malformed / partial → all-default.
  * Returns the effective config object; never throws.
+ *
+ * Only parses the sections this extension consumes (append / capability).
+ * The config file's `version` / `replace` fields belong to the runtime-side
+ * `--system-prompt` consumer (ADR-0044) and are intentionally not parsed here.
  */
 function readConfig(dataDir: string): {
-  version: number
-  replace: { enabled: boolean; prompt: string }
   append: { enabled: boolean; prompt: string }
+  capability: { enabled: boolean }
 } {
   const parsed = readJsonIfValid(path.join(dataDir, CONFIG_FILE))
   if (!parsed) {
     return {
-      version: 1,
-      replace: { enabled: false, prompt: '' },
       append: { enabled: false, prompt: '' },
+      // capability 默认值与解析语义同向：缺 config → 开（见 readCapabilityEnabled）
+      capability: { enabled: true },
     }
   }
   // Merge defensively — every field has its own default.
-  // replace 字段仅防御性解析保持 config 结构完整，不参与本 hook 逻辑——
-  // replace 走 --system-prompt CLI（ADR-0044），hook 只处理 append。
   return {
-    version: typeof parsed.version === 'number' ? parsed.version : 1,
-    replace: readSection(parsed.replace),
     append: readSection(parsed.append),
+    capability: { enabled: readCapabilityEnabled(parsed.capability) },
   }
 }
 
+/**
+ * capability 段开关解析——方向与 readSection 刻意相反（设计 D6 防照抄锚点）：
+ * 仅显式布尔 `false` 关闭；缺字段（v1 存量 json）/字段形态不对（如字符串
+ * "false"）/capability 非对象/文件损坏（readConfig 前置收敛）→ true。
+ * 原因：replace/append 是用户显式配置（缺省关闭才安全），capability 是 taiji
+ * 内置告知（默认开是交付语义）——fail-safe 方向各自服务于所属字段的语义。
+ */
+function readCapabilityEnabled(raw: unknown): boolean {
+  if (!isJsonObject(raw)) return true
+  return raw.enabled !== false
+}
+
 /** Read a JSON file and return it as an object; missing / malformed / non-object → null. */
 function readJsonIfValid(filePath: string): Record<string, unknown> | null {
   try {
@@ -192,7 +377,7 @@ function isJsonObject(v: unknown): v is Record<string, unknown> {
   return !!v && typeof v === 'object'
 }
 
-/** Defensive field parsing for a `replace`/`append` config section. */
+/** Defensive field parsing for the `append` config section. */
 function readSection(raw: unknown): { enabled: boolean; prompt: string } {
   const section = isJsonObject(raw) ? raw : {}
   return {
@@ -202,8 +387,8 @@ function readSection(raw: unknown): { enabled: boolean; prompt: string } {
 }
 
 /**
- * pi 是否以 --no-context-files / -nc 启动。用户显式退出 AGENTS.md / CLAUDE.md
- * 发现时，全局文件不得从这条通路溜回来。pi CLI 把 -nc 视为 --no-context-files
+ * pi 是否以 --no-context-files / -nc 启动。用户显式退出 AGENTS.md
+ * 自动发现时，全局文件不得从这条通路溜回来。pi CLI 把 -nc 视为 --no-context-files
  * 的等价短形式（cli/args.ts），两种形式都必须命中守卫——与镜像侧
  * （argv-mirror.ts 同样解析两种形式）保持一致。
  */
@@ -219,6 +404,18 @@ function withGlobalInstructions(prompt: string): string {
   return prompt + '\n\n# Global instructions (' + global.path + ')\n\n' + global.content
 }
 
+/**
+ * Append the fixed taiji capability section（labeled header 与 global 注入段同构）。
+ * 生效粒度 = 下一 turn：本 hook 每 turn 读 config（mtime 缓存判变），改开关 → 写
+ * system-prompt.json → 下一 turn 读到新值——当前 turn 不受影响（机制既有，非新增）。
+ * 会话产物目录路径每 turn 经 ctx 重新推导（会话切换/新建即生效）。
+ */
+function withCapabilitySection(prompt: string, ctx?: ExtensionContext): string {
+  const cfg = readConfig(resolveDataDir())
+  if (!cfg.capability.enabled) return prompt
+  return prompt + '\n\n' + renderCapabilitySection(resolveArtifactsDirFromCtx(ctx))
+}
+
 /** Read the append config and apply it to the prompt (empty append → unchanged). */
 function withAppendPrompt(prompt: string): string {
   const cfg = readConfig(resolveDataDir())
@@ -228,13 +425,13 @@ function withAppendPrompt(prompt: string): string {
 
 /**
  * Build the injected system prompt. Injection order per turn:
- * base prompt → global instructions → append config (the explicitly
- * configured text wins last). Returns the new systemPrompt, or undefined
- * when nothing changed.
+ * base prompt → global instructions → taiji capability section → append
+ * config (the explicitly configured text wins last). Returns the new
+ * systemPrompt, or undefined when nothing changed.
  */
-function buildSystemPrompt(event: BeforeAgentStartEvent): { systemPrompt: string } | undefined {
+function buildSystemPrompt(event: BeforeAgentStartEvent, ctx?: ExtensionContext): { systemPrompt: string } | undefined {
   const basePrompt = typeof event.systemPrompt === 'string' ? event.systemPrompt : ''
-  const newPrompt = withAppendPrompt(withGlobalInstructions(basePrompt))
+  const newPrompt = withAppendPrompt(withCapabilitySection(withGlobalInstructions(basePrompt), ctx))
   return newPrompt === event.systemPrompt ? undefined : { systemPrompt: newPrompt }
 }
 
@@ -261,9 +458,9 @@ function logHookFailure(err: unknown): void {
 }
 
 export default function (pi: ExtensionAPI): void {
-  pi.on('before_agent_start', (event: BeforeAgentStartEvent) => {
+  pi.on('before_agent_start', (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
     try {
-      return buildSystemPrompt(event)
+      return buildSystemPrompt(event, ctx)
     } catch (err) {
       // Never block the agent loop.
       logHookFailure(err)