@zhushanwen/pi-system-prompt 1.1.5 → 1.2.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zhushanwen/pi-system-prompt",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "System prompt injection extension for Pi — reads config and appends to system prompt",
   "type": "module",
   "main": "src/index.ts",
-  "xyz-agent": {
+  "taiji": {
     "role": "taiji"
   },
   "pi": {
@@ -32,7 +32,7 @@
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.1"
+    "@zhushanwen/pi-extension-logger": "0.6.1"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

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 指向假目录，不碰真实文件系统）。
  *
@@ -36,10 +42,15 @@ vi.mock('node:fs', () => ({
   statSync: vi.fn(),
 }))
 
-const DATA_DIR = '/xyz-test/data'
-const GLOBAL_DIR = '/xyz-test/global-agents'
+const DATA_DIR = '/taiji-test/data'
+const GLOBAL_DIR = '/taiji-test/global-agents'
 const CONFIG_PATH = path.join(DATA_DIR, 'system-prompt.json')
 
+/** capability 段 header 锚（文案变更须同步本锚，红 = 提醒评审段文本变化） */
+const CAP_HEADER = '# TaiJi capabilities'
+/** 既有用例隔离关注点用的「capability 显式关闭」config 片段 */
+const CAP_OFF = '"capability": {"enabled": false}'
+
 /** hook 注册表桩（参照 msg-id-mapper harness 模式） */
 function createHarness(): { beforeAgentStart: (event: BeforeAgentStartEvent) => unknown } {
   const handlers = new Map<string, (...args: unknown[]) => unknown>()
@@ -114,15 +125,15 @@ function setupFs(setup: FsSetup = {}): void {
   })
 }
 
-const ENV_KEYS = ['XYZ_AGENT_DATA_DIR', 'XYZ_GLOBAL_AGENTS_DIR', 'PI_CODING_AGENT_DIR'] as const
+const ENV_KEYS = ['TAIJI_AGENT_DATA_DIR', 'TAIJI_GLOBAL_AGENTS_DIR', 'PI_CODING_AGENT_DIR'] as const
 const savedEnv: Record<string, string | undefined> = {}
 const savedArgv = process.argv
 
 beforeEach(() => {
   vi.clearAllMocks() // 清跨用例的 fs mock 调用记录（「守卫不触发」类断言依赖零计数）
   for (const k of ENV_KEYS) savedEnv[k] = process.env[k]
-  process.env.XYZ_AGENT_DATA_DIR = DATA_DIR
-  process.env.XYZ_GLOBAL_AGENTS_DIR = GLOBAL_DIR
+  process.env.TAIJI_AGENT_DATA_DIR = DATA_DIR
+  process.env.TAIJI_GLOBAL_AGENTS_DIR = GLOBAL_DIR
   delete process.env.PI_CODING_AGENT_DIR
   setupFs()
 })
@@ -136,62 +147,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 +214,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' },
     })
@@ -241,7 +325,7 @@ describe('-nc / --no-context-files 守卫（contextFilesDisabled）', () => {
 
   it('argv 含 -nc 短形式 → 同样跳过 global 注入（与 argv-mirror 两种形式一致）', () => {
     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' },
     })
@@ -272,9 +356,11 @@ describe('global 候选文件选择（readGlobalAgentsFile）', () => {
     expect(result!.systemPrompt).toContain(path.join(GLOBAL_DIR, 'CLAUDE.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 +397,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 +435,19 @@ 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) })
   })
 })

package/src/index.ts

@@ -4,9 +4,13 @@
  * 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
+ *  4. Reads the global instructions file `~/.agents/AGENTS.md` (candidates
  *     AGENTS.md / AGENTS.MD / CLAUDE.md / CLAUDE.MD) 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`
@@ -14,11 +18,12 @@
  *     targets the global agents directory and never picks up override files.
  *     Opt-in by file existence: no file → no injection. Skipped when
  *     pi was spawned with `--no-context-files` (consistent with pi's native
- *     context-file opt-out). `XYZ_GLOBAL_AGENTS_DIR` overrides the global
+ *     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.
@@ -30,7 +35,7 @@ import { readFileSync, readdirSync, statSync } from 'node:fs'
 import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-coding-agent'
 import { getLogger } from '@zhushanwen/pi-extension-logger'
 
-const logger = getLogger('xyz-system-prompt-extension')
+const logger = getLogger('taiji-system-prompt-extension')
 
 const CONFIG_FILE = 'system-prompt.json'
 
@@ -68,11 +73,27 @@ function cachedReadFileSync(filePath: string): string | null {
  */
 const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
 
+/**
+ * taiji capability 固定注入段（设计 D6）：告知 AI 本渲染器的能力面，让新会话无需
+ * 用户手动教。常量放扩展源码内（版本化随 feature 走，非用户配置——用户只持有
+ * on/off 开关，不持有文案本身）。文案英文，与 pi system prompt 语言一致；四点 =
+ * 内联 HTML 白名单面 / 相对图片 cwd 解析 / 相对链接 cwd 解析（与反引号白名单路径
+ * 自动链接化同基准、校验面差异如实）/ 远程图片不渲染 + 反引号规约。
+ */
+const TAIJI_CAPABILITY_SECTION = `# TaiJi capabilities
+
+How TaiJi renders your markdown responses:
+
+- Inline HTML is rendered with a GitHub-grade tag allowlist. Script/style elements and style/class attributes are stripped.
+- 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.
  *
  * Priority:
- *  1. `process.env.XYZ_AGENT_DATA_DIR` (explicit)
+ *  1. `process.env.TAIJI_AGENT_DATA_DIR` (explicit)
  *  2. `path.resolve(process.env.PI_CODING_AGENT_DIR ?? '', '..')`
  *     (PI_CODING_AGENT_DIR == <dataDir>/agent, one level up == dataDir)
  *
@@ -80,7 +101,7 @@ const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE
  * layout shape is handled — one level up. An OLD-layout value
  * (`<dataDir>/pi/agent`, pre-migration) would resolve to `<dataDir>/pi`,
  * accepted here on purpose: in every shipped scenario the runtime injects
- * XYZ_AGENT_DATA_DIR (priority 1 covers it), so priority 2 only serves
+ * TAIJI_AGENT_DATA_DIR (priority 1 covers it), so priority 2 only serves
  * standalone hosts already on the new layout. session-reader's
  * discovery/env.ts strips both shapes for its diagnostics; this resolver
  * deliberately stays single-shape (registered divergence, not a bug).
@@ -89,8 +110,8 @@ const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE
  * take effect without reloading the extension.
  */
 function resolveDataDir(): string {
-  if (process.env.XYZ_AGENT_DATA_DIR) {
-    return process.env.XYZ_AGENT_DATA_DIR
+  if (process.env.TAIJI_AGENT_DATA_DIR) {
+    return process.env.TAIJI_AGENT_DATA_DIR
   }
   return path.resolve(process.env.PI_CODING_AGENT_DIR ?? '', '..')
 }
@@ -99,15 +120,15 @@ function resolveDataDir(): string {
  * Resolve the global agents directory.
  *
  * Priority:
- *  1. `process.env.XYZ_GLOBAL_AGENTS_DIR` (explicit override; tests / escape
+ *  1. `process.env.TAIJI_GLOBAL_AGENTS_DIR` (explicit override; tests / escape
  *     hatch)
  *  2. `~/.agents` (the user-global agents dir that also hosts skills/templates)
  *
  * Re-read on every handler invocation so env changes take effect.
  */
 function resolveGlobalAgentsDir(): string {
-  if (process.env.XYZ_GLOBAL_AGENTS_DIR) {
-    return process.env.XYZ_GLOBAL_AGENTS_DIR
+  if (process.env.TAIJI_GLOBAL_AGENTS_DIR) {
+    return process.env.TAIJI_GLOBAL_AGENTS_DIR
   }
   return path.join(homedir(), '.agents')
 }
@@ -157,6 +178,7 @@ 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) {
@@ -164,6 +186,8 @@ function readConfig(dataDir: string): {
       version: 1,
       replace: { enabled: false, prompt: '' },
       append: { enabled: false, prompt: '' },
+      // capability 默认值与解析语义同向：缺 config → 开（见 readCapabilityEnabled）
+      capability: { enabled: true },
     }
   }
   // Merge defensively — every field has its own default.
@@ -173,9 +197,22 @@ function readConfig(dataDir: string): {
     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 {
@@ -219,6 +256,17 @@ 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 不受影响（机制既有，非新增）。
+ */
+function withCapabilitySection(prompt: string): string {
+  const cfg = readConfig(resolveDataDir())
+  if (!cfg.capability.enabled) return prompt
+  return prompt + '\n\n' + TAIJI_CAPABILITY_SECTION
+}
+
 /** Read the append config and apply it to the prompt (empty append → unchanged). */
 function withAppendPrompt(prompt: string): string {
   const cfg = readConfig(resolveDataDir())
@@ -228,13 +276,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 {
   const basePrompt = typeof event.systemPrompt === 'string' ? event.systemPrompt : ''
-  const newPrompt = withAppendPrompt(withGlobalInstructions(basePrompt))
+  const newPrompt = withAppendPrompt(withCapabilitySection(withGlobalInstructions(basePrompt)))
   return newPrompt === event.systemPrompt ? undefined : { systemPrompt: newPrompt }
 }
 
@@ -242,7 +290,7 @@ function buildSystemPrompt(event: BeforeAgentStartEvent): { systemPrompt: string
  * 落盘诊断，不泄露配置内容。
  *
  * 通道：extension-logger 的 error → appendEntry 写入 session JSONL（需 setPiHandle
- * 注入 pi handle 后生效）；XYZ_AGENT_DEBUG=1 时另落文件日志。仅当 logger 自身抛错
+ * 注入 pi handle 后生效）；TAIJI_AGENT_DEBUG=1 时另落文件日志。仅当 logger 自身抛错
  * 时才兜底 process.stderr.write（下方 catch），不外泄到 agent loop。
  */
 function logHookFailure(err: unknown): void {
@@ -252,7 +300,7 @@ function logHookFailure(err: unknown): void {
   } catch (nestedErr) {
     // best-effort：logger 抛错时的终极兜底 process.stderr.write——其内部吞错不会抛，仍不外泄到 agent loop。
     try {
-      process.stderr.write(`[xyz-system-prompt-extension] logHookFailure also failed: ${String(nestedErr)}\n`)
+      process.stderr.write(`[taiji-system-prompt-extension] logHookFailure also failed: ${String(nestedErr)}\n`)
     } catch (finalErr) {
       /* 完全静默：两层兜底都失败时无处可写 */
       void finalErr