Apollo School Policy Internal Agent

@apollo-music/[email protected] 是双 Agent PoC 的内部主体，固化政策文件与学生交付投影均由它负责生成和管理。它一方面通过独立 SDK JSON-RPC child 组合已发布的 School Expert 0.3.1 的 sealed SQLite、对象级政策树与官网证据；另一方面在同一发布包中提供受控的确定性政策维护入口 apollo-school-policy-internal-maintain 和学生交付入口 apollo-school-policy-internal-delivery。已发布的 Analyzer 0.3.1 只是可替换的递归校验、建索引和 release v2 封装/发布执行器，不是本 Agent 的业务主体、Persona 或对外接口。

本 README 描述的精确版本是 Internal Agent 0.3.2。部署时应从授权 npm registry 固定安装 @apollo-music/[email protected]，并以干净环境中的精确版本、依赖闭包和制品哈希复验作为部署证据。workspace 构建、本地 tarball 与 npm 发布/复装状态属于发布审计，不写入包内长期说明。

0.3.2 保持 0.3.1 的工具、数据和模型合同，将 Cordis vendor cohort 升级到 @deepseek-ai/[email protected] 与 @deepseek-ai/[email protected]，并使用 loader 1.0.3 的 Node 24 内部 ESM loader 能力检测修复。

专业标题译审使用同包的独立内部 JSON-RPC Agent：apollo-school-policy-title-translator-jsonrpc。生成器通过官方 @deepseek-ai/[email protected] 复用一个 Harness 进程、为每批创建新 Session，路由固定为 dashscope-intl/qwen3.8-max。译审 Agent 挂载 fail-closed 的 @apollo-music/[email protected]；插件自身把 Authority 固定为 https://apollomusic-poc1.fde0.com/kb/terminology，不接受 URL 覆盖，也不包含本地术语服务或 P0 fallback。Catalog、Resolver、鉴权或网络不可用时停止译审。该流程的对外数据授权仅包含公开官网专业标题，不包含学生、客户或内部业务数据。

线上术语审计报告可通过 --repair-report <translation-audit.json> 送回同一译审 Agent 做定向修正。修正只读取 schema-v2 报告中现有的 required / sourceTerm / forbidden 约束，不直连术语 API，也不增加本地术语表。必须先有完整 schema-v2 checkpoint；所有批次通过严格 JSON、基础译名和报告约束校验后，才会原子覆盖 checkpoint 并重写 generated TypeScript。

学生页面的正文编辑和主编审核是两个隔离的内部 DSH Runtime，而不是把 Analyzer 记录直接套模板。apollo-school-policy-page-editor-jsonrpc 接收单页所需的完整官网原文、结构化线索、规定章节和调用方已经核实的可选教师照片元数据，输出学生页面严格 JSON；apollo-school-policy-page-reviewer-jsonrpc 在另一个 Harness 进程中接收同一来源与初稿，独立输出 verdict + issues + guidance。Host 必须为两者各持有一个独立的 DeepSeekHarness，每个页面分别调用一次不带 sessionId 的 run()，因此编辑页与审核页各自都是 fresh Session，且审核 Agent 看不到编辑 Session 的历史。通常由调用方在组装 sourceDocuments 时完成官网访问或必要的 Computer Use，Runtime 不靠跨页记忆弥补缺失来源。

成功初稿根结构固定为 titleZh/titleOriginal/leadZh/leadCitations/sections，教师或讲师页可额外带调用方给出的 photo。每个 section 只有 id/headingZh/blocks，每个 block 只有 zh/citations；每条 citation 有 sourceId/original，并可以用 displayOriginal 选择学生可见的连续原文摘录。displayOriginal=null 表示该 citation 只进入 HTML 溯源注释；旧 artifact 省略字段时仍显示完整 original。每个中文导语或 block 至少保留一条可见 citation。一个自然中文段落可按事实出现顺序引用多个官网语义块，不再接受旧的单一 leadOriginal/leadSourceId 或 block 级 original/sourceId 结构。@apollo-music/dsh-agent-school-policy-internal/student-page-contract 提供严格 JSON 解析、固定章节白名单与来源约束：每条 citation.original 必须是其声明的 sourceDocuments.sourceId 中可精确匹配的规范化原文片段，字符串 displayOriginal 必须是 original 规范化后的连续子段，不允许跨来源拼接后只标一个 ID。请求中的章节规格只能从该 page type 的白名单按规范顺序选取，required 必须显式给出；规范必选章节必须存在且为 true，其他章节可在官网有实质内容时提升为必选。初稿必须包含全部 required=true 章节，只能按请求顺序选择有实质官网内容的可选章节，并保持 ID 与中文标题完全一致。照片必须逐字段原样回显，没有输入照片就禁止输出照片。审核 Agent 还要通读官网原文，发现有相关实质内容却遗漏可选章节时强制 revise。只有在 issues=[] 且 guidance=[] 时才能 pass；任一事实、日期、双语、结构、可读性或照片问题都强制 revise 并给出具体修订动作。

审核通过后，Host 同时写入两类完整性记录：reviewedContentHash 绑定审核 Session 实际看到的学生文案与来源，artifactContentHash 进一步绑定原文语言、来源 URL/网页 meta 更新时间及官方肖像的 URL、文件哈希和尺寸。最终源请求（包括定向官网补充后的 sourceDocuments）以不可变快照和指纹留在内部 artifact；恢复生成时必须先通过学生交付侧同一严格 v2 loader，不能用一套较弱的手写字段判断提前复用。

两个 Runtime 都固定 dashscope-intl/qwen3.8-max、官方 DSH 0.1.1-rc.2 和线上术语 Authority https://apollomusic-poc1.fde0.com/kb/terminology。启动时分别对线上 Catalog 与 Resolver 做 fail-closed 预检；Sidecar 后续报告 degraded 时 Persona 只能输出 TERMINOLOGY_UNAVAILABLE，严格页面/审核解析器会拒绝该结果。它们共享一个状态根但写入强隔离子目录：

• APOLLO_STUDENT_PAGE_STATE_ROOT：绝对路径；自动使用 editor/sessions 与 reviewer/sessions；
• APOLLO_STUDENT_PAGE_MODEL_API_KEY：qwen3.8-max 模型凭证；
• APOLLO_TERMINOLOGY_READ_API_KEY：线上术语只读凭证。
• APOLLO_STUDENT_PDF_REQUIREMENTS_ROOT：已经发布的《学生 PDF 渲染与内容验收细则》registry；两个 Runtime 启动时读取同一 current.json，逐字节校验 SHA-256，并在非 baseline 时反向绑定唯一 render_requirements.revision.applied 事件。

编辑 Runtime 另有仅用于“来源不足重试”的可选 Playwright MCP seam，默认完全关闭，审核 Runtime 永远不挂浏览器。Host 先用普通编辑进程；只有收到 SOURCE_INSUFFICIENT，且本页 objectHints.liveOfficialUrls 已列出精确官网 URL 时，才启动一个新的、只服务该页的编辑进程，并设置：

• APOLLO_STUDENT_PAGE_EDITOR_LIVE_BROWSER=1；
• APOLLO_STUDENT_PAGE_EDITOR_ALLOWED_ORIGINS=https://official.example.edu，多个精确 HTTPS origin 用逗号分隔，不接受路径、凭证或通配漫游。

开启时 Host Profile 必须显式安装现有 @apollo-music/[email protected]；它是可选 peer，普通进程不加载也不启动 Chromium，开启但未安装则启动失败。Host 先用裸 HTTP/PDF 读取，失败时再用该页独立的 Playwright context 捕获精确官网页面；新正文按语义块加入 sourceDocuments 后，才启动新的可浏览编辑 Session。编辑 Persona 只能打开 liveOfficialUrls 和 allowlist 内同一官网 origin 的对象相关页面，禁止搜索引擎、第三方站点或跨域漫游；正文仍只能引用已经回灌的 sourceDocuments。审核 Runtime 永远不浏览网页，并且不会看到上一轮 reviewer guidance。

school-policy-core 是工作区内部实现，不单独发布。本 Agent 构建时把其工具和维护 CLI 分别打成包内单文件，并把成熟的数据/DSH 库保留为普通精确依赖；发布包既没有私有 registry 依赖，也不会跟随 pnpm workspace 软链接写出越界 tar 条目。

本 Agent 不直接面向企业微信员工或未来微信客服学生；只接受对外院校政策专家通过唯一 school_policy_internal 网关发送的完整自包含任务。JSON-RPC 面只允许 dashscope-intl/qwen3.8-max，无自动模型回退，也没有 Web、企微 Bridge、任意文件写权限或交互审批。Host/渠道访问控制是唯一授权边界；能访问受控 Agent 的用户无需另一层授权标记或批准，其明确、可追溯的用户原话直接成为两个固定 apply 工具的可用指令。Agent 不根据用户自报身份升权，也不内建复杂 RBAC。运维生成 CLI 仍由运维人员显式调用。

模型工具固定为 10 个：

• apollo_policy_status：校级 policy v2 状态、对象数量和 manifest 校验结果；
• apollo_policy_links：按政策主题读取官方链接；
• apollo_policy_programmes：在单校 scope 中列出/搜索专业，返回稳定 programme_key；
• apollo_policy_programme_detail：按精确 key 读取单专业详情或指定章节；
• apollo_policy_professors：在单校 scope 中列出/搜索教授与 Prof. 称谓复核候选，返回稳定 person_key；
• apollo_policy_professor_detail：按精确 key 读取单教授详情或指定章节；
• apollo_policy_historical_reference：按学校/专业窄读一次性授权封存的微信群业务知识，仅作历史经验或专业信息参考；
• apollo_pdf_requirements_read：读取当前已生效 PDF 细则版本、hash 与正文；
• apollo_pdf_requirements_apply：只在已授权明确指令下校验完整新细则，单次写入不可变版本、追加 render_requirements.revision.applied 并更新 current；
• apollo_policy_feedback_apply：校验已授权政策纠正、官方来源与 scope，单次追加绑定新 release 的 feedback.applied 事件。

政策/对象查询、历史参考和已生效细则读取均为只读。两个 apply 工具只能在各自固定根执行受限完整校验与原子变更，不接受调用方选择的文件路径、SQL 或自定义 DSL。政策纠正一次调用只追加一个 feedback.applied 事件，绑定 actor/time/官方来源/sealed release id+版本+manifest SHA-256 并返回 state=applied；缺少官方 URL 或任何校验失败时不修改当前 release。PDF 细则 apply 同样只有 applied/不生效两种结果，不存在 pending→approved/rejected 二次审批链。

微信群原始导出不进入 npm 包或 runtime 查询面。业务人员在部署信任边界内将真实摘要整理为受控 JSONL，再授权单次 business-knowledge seal；seal 校验精确输入字节、消息定位、学校/专业 scope，并用同校已验证 policy programme index 检查 programme_key，然后直接生成绑定 records.jsonl 与 manifest 的 immutable snapshot。每次模型查询都重读实际文件，hash/count/scope 或路径任一不符即失败关闭。该来源永远只是历史经验/专业信息参考，不能覆盖 sealed policy 或当前官网；没有真实封存内容时工具继续返回 unavailable，不用模型或测试记录补造。

《学生 PDF 渲染与内容验收细则》使用独立 registry：current.json 只指向 published/<version>.md 并记录 UTF-8 精确字节 SHA-256。当前受控基线为 1.1.0，canonical SHA-256 是 f36adf858622a0d29337d1cfd77d2f0316f23bcd899c594021bd389eeb238538，并按 15 个必需语义 section ID 验证客户条款未漏装。共享 loader 从 registry 的绝对路径根开始逐组件校验 realpath containment，拒绝任一中间符号链接或非普通文件。唯一无事件例外是固定 hash 的全新 revision_id=baseline 1.1.0；首个修订版本必须严格高于 1.1.0。已授权修改请求由 apollo_pdf_requirements_apply 完整校验后，单次写入不可变文档、追加唯一 render_requirements.revision.applied 事件并原子更新 current；非 baseline current 必须反向匹配该 applied 事件。页面编辑、独立盲审和学生 PDF CLI 均只读取 current。

每校 policy v2 目录包含校级导航、programmes/、professors/ 和 references/。每个纳入或复核的音乐相关专业有一个详细 Markdown；每位结构化身份已确认的教授，以及由明确绑定本人的官网 faculty evidence 发现、但身份仍待复核的教授称谓候选，分别有独立介绍文件。人物页、人事公告、院系/目录和任教证据必须能直接归属本人；他人称谓、外部教授事件或拼接目录中归属不明的 Prof. 不提升候选。professor_identity 与 music_scope 分开记录，正式 role_type=professor 才是结构化身份 confirmed。

学生投影不会把 professor-index.jsonl 的全部候选自动称为教授：只有 professor_identity=confirmed，或官网称谓、姓名、角色类型/角色原文明确写出 Professor、Prof. 或等价教授身份时，才进入教授类别；其余对象只有在存在当前音乐教学角色或任教记录时才可进入讲师类别。共享专业页和共享师资目录不能作为任一对象的完整页面来源；只有唯一归属 URL 才能全文/实时补取，共享页面只给当前对象提供可靠定位或明确点名的区块，共享人物页照片还必须通过本人身份匹配。

专业与教授只按已验证显式关系双向引用，机器索引保留 school-scoped key。专业日期同时保留官网源值与格式元数据：完整日期显示 ISO YYYY-MM-DD；无年份循环日期显示为 --MM-DD，并标记 recurring-month-day、range 或 set；时间与时区单独记录，绝不把解析锚点写成政策年份。教师在册、任教学科、专业关系、可选导师与当期招生不能相互推导，缺证据时明确“官网未明确”。校级内容只保留真正校级事实和对象导航，不把专业记录机械复制到摘要。

0.3.x 提供独立学生交付投影：每个专业及每位官网现任教授/讲师生成一份学生页面；每条先写正常中文段落，下一段以次级样式放对应德文或英文，不使用机器式双语标签。专业目录和章节统一显示中文在前、原名在后。每校合成一份含目录、页码、书签、专业和师资章节的连续可读 PDF，不附末尾链接集合。规范 HTML 是 PDF 唯一源；逐段来源与截图证据进入 HTML 内部校对层和 evidence-review/，学生渲染会物理剔除该层。bilingual 显示对应原文，zh-only 物理移除原文而不改变中文事实。学生日期只取官网自身更新时间 meta，抓取时间只留在校对包。内部状态、对象主键、证据主键、哈希、裁定和审核措辞不进入学生内容。完整规则以当前已生效《学生 PDF 渲染与内容验收细则》为准。

全校或单校政策文件生成：

apollo-school-policy-internal-maintain build --all --kb-root /absolute/policy-kb
apollo-school-policy-internal-maintain build --school udk-berlin --kb-root /absolute/policy-kb
apollo-school-policy-internal-maintain status --kb-root /absolute/policy-kb

一次生成全部学校的学生 Markdown、截图和 PDF：

apollo-school-policy-internal-delivery build --all \
  --kb-root /absolute/policy-kb \
  --editorial-root /absolute/approved-editorial \
  --render-requirements-root /absolute/published-render-requirements \
  --out-root /absolute/delivery-output \
  --python /absolute/python-with-reportlab-pdfplumber-pillow-pypdf \
  --chrome /absolute/Google-Chrome \
  --font /absolute/Arial-Unicode.ttf

该入口是运维维护能力，不挂载给企微查询模型。它只对学生内容实际采用的官网证据做定向截图；HTML 全程离线渲染归档原文片段，PDF 截取原始页面，全部写入内部证据校对包。学生 Markdown 与 PDF 使用同一个 student-school 投影模型；任何对象无公开事实、校对截图失败、证据包图片链接失效、学生内容出现内部措辞或 PDF 字体/目录/链接检查失败时整校失败。

生成结果通过后，可替换的 Analyzer 0.3.1 再负责递归校验、建索引、seal 和 publish。release v2 manifest 声明全部嵌套对象/references 文件、逐文件 SHA-256 与 tree hash；旧 contract、越界路径、缺文件、跨校 scope 或 hash 不一致一律失败关闭，不能回退读取 v1。

必需环境：

• APOLLO_KB_ROOT：已经校验的 release v2 数据根；
• APOLLO_SCHOOL_POLICY_MODEL_API_KEY 与 APOLLO_SCHOOL_POLICY_MODEL_BASE_URL；
• APOLLO_SCHOOL_POLICY_MODEL_PROVIDER=dashscope-intl；
• APOLLO_SCHOOL_POLICY_MODEL=qwen3.8-max；
• APOLLO_SCHOOL_POLICY_SESSION_ROOT；
• APOLLO_SCHOOL_POLICY_ARCHIVE_CACHE_ROOT；
• APOLLO_SCHOOL_POLICY_FEEDBACK_FILE。
• APOLLO_STUDENT_PDF_REQUIREMENTS_ROOT：必需的已生效细则 registry；
• APOLLO_PUBLISHED_BUSINESS_KNOWLEDGE_ROOT：可选的一次性 sealed 业务知识 snapshot。

所有状态路径应位于专属 DSH_HOME/school-policy-internal/ 下。Host Provider 通过 process.execPath 启动包内 dist/jsonrpc-bin.js，不依赖 PATH 或 npx。

npm install
npm run typecheck
npm test
npm pack --dry-run

当前全量 v2 基线为 33/33 校、1,407 个专业文件（music_scope confirmed=1,394、review=13）、2,360 个教授候选文件（身份 confirmed=1,089、review=1,271；音乐范围 confirmed=2,152、review=208）、2,755 条有效关系/5,510 个双向端点、54,071 条 evidence 和 13 项输入审计事项。release manifest 声明 4,229 个内容文件、142,978,263 个内容字节。

全量 QA 为 0 errors / 0 warnings：核验 18,506 个本地链接、24,093 个日期源值、15,819 个精度元数据、4,071 个 time/timezone 标记、366 个循环日期表达，以及全部 2,360 份“不从任职推断招生”声明。

不可变 release 为 20260823T114755Z-29e4da10a42a；manifest SHA-256 为 29e4da10a42a0d0e1e24488597e8bacad0d76de25a6e6999a586bd2b9a139f12，archive SHA-256 为 8bf5c15636b981619ce5ed314d7a9d3ba2c338e9352eeb043f943cfeafd2ea27。该 release 已 seal、发布到 stable、由独立客户端下载并 verify；它取代旧 stable 指针，但旧不可变 release 保留。