@zhushanwen/pi-system-prompt 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt",
-  "version": "1.2.0",
+  "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

@@ -33,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', () => ({
@@ -51,8 +57,8 @@ const CAP_HEADER = '# TaiJi capabilities'
 /** 既有用例隔离关注点用的「capability 显式关闭」config 片段 */
 const CAP_OFF = '"capability": {"enabled": false}'
 
-/** hook 注册表桩（参照 msg-id-mapper harness 模式） */
-function createHarness(): { beforeAgentStart: (event: BeforeAgentStartEvent) => unknown } {
+/** 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) => {
@@ -61,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
 }
@@ -323,7 +329,7 @@ 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"}, ${CAP_OFF}}`,
       globalEntries: ['AGENTS.md'],
@@ -335,25 +341,25 @@ 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：global 不注入、不抛错（capability 默认段仍在）', () => {
@@ -451,3 +457,171 @@ describe('cachedReadFileSync（mtime 级内容缓存，KV-cache 稳定性改造
     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

@@ -11,7 +11,7 @@
  *  3. When `append.enabled === true` and `append.prompt` is non-blank,
  *     appends the user's text to the event's systemPrompt.
  *  4. Reads the global instructions file `~/.agents/AGENTS.md` (candidates
- *     AGENTS.md / AGENTS.MD / CLAUDE.md / CLAUDE.MD) every turn and appends it
+ *     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
@@ -32,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')
@@ -66,28 +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']
 
 /**
- * taiji capability 固定注入段（设计 D6）：告知 AI 本渲染器的能力面，让新会话无需
- * 用户手动教。常量放扩展源码内（版本化随 feature 走，非用户配置——用户只持有
- * on/off 开关，不持有文案本身）。文案英文，与 pi system prompt 语言一致；四点 =
- * 内联 HTML 白名单面 / 相对图片 cwd 解析 / 相对链接 cwd 解析（与反引号白名单路径
- * 自动链接化同基准、校验面差异如实）/ 远程图片不渲染 + 反引号规约。
+ * 对话流渲染管线的 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* 事件处理器同理不存活）。
+ * 通配项以 `*` 结尾，对拍机检按前缀比对剥除语义。
  */
-const TAIJI_CAPABILITY_SECTION = `# TaiJi capabilities
+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 tag allowlist. Script/style elements and style/class attributes are stripped.
+- 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.
@@ -116,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.
  *
@@ -173,29 +325,25 @@ 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) },
   }
@@ -229,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 {
@@ -239,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 同样解析两种形式）保持一致。
  */
@@ -260,11 +408,12 @@ function withGlobalInstructions(prompt: string): string {
  * 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): string {
+function withCapabilitySection(prompt: string, ctx?: ExtensionContext): string {
   const cfg = readConfig(resolveDataDir())
   if (!cfg.capability.enabled) return prompt
-  return prompt + '\n\n' + TAIJI_CAPABILITY_SECTION
+  return prompt + '\n\n' + renderCapabilitySection(resolveArtifactsDirFromCtx(ctx))
 }
 
 /** Read the append config and apply it to the prompt (empty append → unchanged). */
@@ -280,9 +429,9 @@ function withAppendPrompt(prompt: string): string {
  * 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(withCapabilitySection(withGlobalInstructions(basePrompt)))
+  const newPrompt = withAppendPrompt(withCapabilitySection(withGlobalInstructions(basePrompt), ctx))
   return newPrompt === event.systemPrompt ? undefined : { systemPrompt: newPrompt }
 }
 
@@ -309,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)