diff --git a/.agents/skills/unidesk-oa/SKILL.md b/.agents/skills/unidesk-oa/SKILL.md index 4865d259..16ea0c6c 100644 --- a/.agents/skills/unidesk-oa/SKILL.md +++ b/.agents/skills/unidesk-oa/SKILL.md @@ -9,9 +9,24 @@ HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理锚定在 UniDesk 仓库 ## 高频规则 -- 项目管理 stable source of truth 在 `project-management/PJ2026-01/`，GitHub issue 承载执行流和证据索引。 +- 项目管理稳定事实源按项目编号维护在 `project-management/PJ*/`，GitHub issue 承载执行流和证据索引。 - 重大项目/方向/课题/子课题层级、任务书、实施方案、测试规格、阶段报告和项目偏离按项目编号目录维护。 - 形成多阶段实施、架构或长期 API/数据模型时，先 SPEC，再实现和 issue 阶段计划。 +- SPEC 规范性正文只定义预期终态： + - 目标能力； + - 稳定边界； + - 目标架构、数据流和接口； + - 原子需求； + - 验收契约。 +- SPEC 不得写入执行态内容： + - 当前实现状态或能力基线； + - 已完成、未完成和当前阻塞； + - 临时运行面、本轮差距和一次性证据； + - 源码路径、作业编号、日志、截图或样片清单。 +- 规格生命周期状态与实现进度必须分离： + - 文档控制可以记录规格已生效、未生效或已废弃； + - 不得在 SPEC 中增加“实现状态”字段或用目标需求宣称能力已经上线。 +- 当前状态进入阶段报告、任务报告、偏离记录或 GitHub issue；验证证据只从这些执行态载体引用 SPEC，不反向写入 SPEC 正文。 - GitHub issue/PR 写入仍走 `$unidesk-gh`；正文必须写目标合并分支/lane。 ## Reference 路由 @@ -22,6 +37,6 @@ HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理锚定在 UniDesk 仓库 ## 常用检查 ```bash -find project-management/PJ2026-01 -maxdepth 3 -type f | sort +find "project-management/${PJ_ID:?请先设置 PJ_ID}" -maxdepth 3 -type f | sort bun scripts/cli.ts gh issue list --repo pikasTech/unidesk --state open --limit 30 ``` diff --git a/.agents/skills/unidesk-oa/agents/openai.yaml b/.agents/skills/unidesk-oa/agents/openai.yaml index ed205a45..8ce626b5 100644 --- a/.agents/skills/unidesk-oa/agents/openai.yaml +++ b/.agents/skills/unidesk-oa/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "UniDesk OA" - short_description: "管理 UniDesk 项目规格目录和 issue 层级。" - default_prompt: "使用本技能规划 project-management/PJ2026-01 项目结构、总规格和相互链接的 GitHub issue 执行记录。" + short_description: "管理 UniDesk 项目终态规格、层级与执行态报告" + default_prompt: "使用 $unidesk-oa 为指定项目编号维护预期终态 SPEC，并把当前状态放入报告或 issue。" diff --git a/.agents/skills/unidesk-oa/references/project-planning.md b/.agents/skills/unidesk-oa/references/project-planning.md index ff932718..07d620e2 100644 --- a/.agents/skills/unidesk-oa/references/project-planning.md +++ b/.agents/skills/unidesk-oa/references/project-planning.md @@ -20,6 +20,19 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏 - 决策依据。 - 稳定验收标准。 +SPEC 只承载预期终态： + +- 目标能力和稳定责任边界。 +- 目标架构、数据流、接口和原子需求。 +- 可重复执行的验收契约。 +- 规格生命周期状态可以记录已生效、未生效或已废弃，但不等于实现进度。 + +SPEC 不承载执行态： + +- 当前实现状态、阶段基线和本轮差距。 +- 已完成、未完成、当前阻塞和临时运行面。 +- 源码路径、commit、PR、作业、日志、截图、样片或一次性验收证据。 + 用 issue 承载执行状态： - 当前负责人和状态。 @@ -30,11 +43,16 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏 - 收口评论。 - 长证据索引、CaseRun registry、运行日志、历史 issue 摘要。 -不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到 `project-management/PJ2026-01`，再从 issue 链接过去。 +阶段报告、任务报告和偏离记录承载跨 issue 的状态汇总。不得为了保存执行进度，把这些内容回填到 SPEC 规范性正文。 + +不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到对应 `project-management/PJ*/` 项目编号目录，再从 issue 链接过去。 不要把长证据正文放进项目管理目录。项目管理目录只承载规格、治理和阶段中心；长证据保留在 GitHub issue。 规格文件和 GitHub issue 的引用规则分开处理： -- `project-management/PJ2026-01/specs/*.md` 不保留单独的迁移来源块；历史来源只写在修改历史 `v0.1` 变更说明中，格式为 `迁移来源 /#`。 +- 规格文件不保留单独的迁移来源块： + - 范围是 `project-management/PJ*/specs/*.md`； + - 历史来源只写在修改历史 `v0.1` 变更说明中； + - 格式为 `迁移来源 /#`。 - 规格文件引用其他规格时，使用同目录相对路径 Markdown 链接，例如 `[PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md)`；不要引用其他规格的 GitHub issue、证据 issue、PR 或裸 `#`。 - GitHub issue/PR 正文和评论中的 issue/PR 引用必须写成 `[#](https://github.com///issues/)` 或 `[#](https://github.com///pull/)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。 @@ -48,6 +66,7 @@ P0 SPEC 必须完成： - 按模板写清文档控制、目的和范围、术语表、系统边界、内部分工、原子需求和过程控制。 - 为涉及实现架构的数据面补齐目标架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 `mermaid`。 - 在 SPEC 中写明后续代码文件头部应标注的 SPEC 编号、短名和实现引用版本。 +- 把正文写成预期终态，不以当前实现、阶段基线或未完成清单解释目标。 后续代码阶段只能在 P0 SPEC 明确后开始。后续讨论改变稳定需求、数据流、接口或验收口径时，先更新 SPEC，再更新 issue 计划。该规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本；自动生成文件、第三方 vendored 文件、纯配置、锁文件和不能承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。 @@ -103,15 +122,15 @@ specs/spec-governance.md # 编号、层级、回写与偏离规 | 层级 | 负责 | 不负责 | 回写到 | | --- | --- | --- | --- | -| L0 | 使命、非目标、当前中心、L1 方向树、全局验收、偏离规则 | PR 细节、CaseRun 日志、日报流水、实现设计 | `project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md` 和 L1 issue | +| L0 | 使命、非目标、预期终态、方向树、全局验收 | 当前中心、PR/CaseRun/日报与实现设计 | L0 规格和 L1 issue | | L1 | 能力域范围、成功标准、L2 课题清单、原始验收类型 | 单个 PR、一次性 smoke、仓库/工具/运行面名称、项目管理动作 | L0 规格和对应 L1 规格文件 | -| L2 | 一个 L1 内的具体课题、交付物、阻塞项、验证计划 | 宽泛能力域或实现细节流水 | L1 issue，重大移动再回写 L0 | +| L2 | 一个 L1 内的具体课题、目标交付物和验证计划 | 当前阻塞、宽泛能力域或实现细节流水 | L1 issue，重大移动再回写 L0 | | L3 | 一个有界验收切片和单一验收路径 | 路线图、多课题计划、父级范围变化 | L2/L1 issue 并带证据 | | L4 | 具体执行：PR、CaseRun、smoke、部署、文档收口 | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1，并带原入口证据 | 分类规则： -- 改变使命、当前中心、L1 列表或全局验收的，属于 L0。 +- 改变使命、预期终态、L1 列表或全局验收的，属于 L0。 - 定义可以容纳多个课题的稳定能力域的，属于 L1。 - 在一个方向内规划具体工作计划的，属于 L2。 - 可以通过一个有界路径验收的，属于 L3。 @@ -122,7 +141,7 @@ specs/spec-governance.md # 编号、层级、回写与偏离规 L0 定义： - 使命和非目标。 -- 当前工作重心。 +- 预期终态。 - 产品入口。 - 方向列表。 - 全局验收标准。 @@ -139,10 +158,10 @@ L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件 每个方向必须回答： - 它服务 L0 目标的哪一部分。 -- 什么状态算完成。 +- 什么终态算完成。 - 涉及哪些仓库、分支、lane。 - 哪个原始用户/运行面入口可以验收它。 -- 当前重要的 L2 课题有哪些。 +- 目标 L2 课题有哪些。 以下内容不能作为 L1 方向： @@ -158,7 +177,7 @@ L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件 - 主责不清楚时，问“什么证据能关闭这个 issue”：硬件资源就绪、Agent 执行生命周期、Harness/RL 证据、客户端/API 行为、用户/管理策略，还是平台交付/运维。 - 先按完成标准判断主责，再看实现表面。CLI、Web 页面、HTTP API、hwpod 工具或服务路由不会自动归入 `客户端`；它们主归属定义正确性的领域。只有当完成标准是 Web、CLI、HTTP API 的入口行为、用户交互、兼容性或输出格式时，`客户端` 才是主责 L1。 -HWLAB Cloud M1 当前 L1 职责矩阵： +HWLAB Cloud M1 L1 职责矩阵： | 编号 | 短名 | 主责 | 不负责 | 交接示例 | | --- | --- | --- | --- | --- | @@ -189,7 +208,7 @@ HWLAB Cloud M1 当前 L1 职责矩阵： ### 硬件池 L2 标准 -`PJ2026-0101 硬件池` 当前 L2 拆分为： +`PJ2026-0101 硬件池` L2 拆分为： | 编号 | 短名 | 主责 | 关联 L1 | 边界 | | --- | --- | --- | --- | --- | diff --git a/.agents/skills/unidesk-oa/references/templates.md b/.agents/skills/unidesk-oa/references/templates.md index 664beab5..b9e03876 100644 --- a/.agents/skills/unidesk-oa/references/templates.md +++ b/.agents/skills/unidesk-oa/references/templates.md @@ -1,5 +1,13 @@ # UniDesk OA 模板 +## SPEC 正文边界 + +- SPEC 只写预期终态、目标能力、稳定边界和验收契约。 +- 文档控制中的“状态”只表示规格生命周期，不表示实现进度。 +- SPEC 不增加“实现状态”“当前基线”“当前阻塞”或“已完成能力”章节。 +- 当前状态、阶段差距和实现证据进入阶段报告、任务报告、偏离记录或 GitHub issue。 +- 源码路径、commit、PR、作业、日志、截图和样片清单不得作为 SPEC 规范性正文。 + ## L0 总规格骨架 ```markdown @@ -9,9 +17,9 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | | | 创建需求规格；如来自历史 issue，只在这里写迁移来源 /#。 | +| v0.1 | | | 创建预期终态需求规格；如来自历史 issue，只在这里写迁移来源 /#。 | -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 ## 正文 @@ -24,7 +32,7 @@ | 编号 | PJ2026-01 | | 短名 | HWLAB | | 层级 | L0 总项目 | -| 状态 | 已生效、已废弃或未生效 | +| 规格状态 | 已生效、已废弃或未生效；只表示规格生命周期 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 规格治理索引 | [规格治理](spec-governance.md) | diff --git a/project-management/PJ2026-02/specs/PJ2026-02-smart-media-factory.md b/project-management/PJ2026-02/specs/PJ2026-02-smart-media-factory.md index 5ec49738..15688863 100644 --- a/project-management/PJ2026-02/specs/PJ2026-02-smart-media-factory.md +++ b/project-management/PJ2026-02/specs/PJ2026-02-smart-media-factory.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于 `/root/selfmedia` 已跑通能力建立智媒工厂 L0 总规格和七个 L1 能力域。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义智媒工厂预期终态和七个 L1 能力域。 | ## 正文 @@ -19,12 +17,17 @@ | 编号 | PJ2026-02 | | 短名 | 智媒工厂 | | 层级 | L0 总项目 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 规格治理索引 | 本文第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只保留稳定使命、范围、术语、系统边界、能力域分工、原子需求和必要过程控制。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文边界如下： + +- 只定义预期终态、目标能力、稳定边界和验收契约； +- 不记录实现进度或阶段基线。 ## 2. 目的和范围 @@ -34,49 +37,56 @@ - 面向科技资讯创作者和技术团队； - 把资讯发现、事实核验、编辑策划、动态图文、配音、字幕、成片和发布材料收敛为本地优先的生产链； -- 当前以嵌入式与 AI 交叉、纯嵌入式和 AI 为首要内容方向； -- 长期成为可配置、可单步调试的技术内容生产基础设施； +- 以嵌入式与 AI 交叉、纯嵌入式和 AI 为首要内容方向； +- 成为可配置、可单步调试的技术内容生产基础设施； - 使每一期节目都能从来源证据追溯到口播、画面、成片和评论区引用。 -### 2.2 当前能力基线 +### 2.2 预期终态 -- 资讯收集： - - 通过 YAML 登记 RSS、Atom、Hacker News API 和人工来源； +智媒工厂终态应同时具备： + +- 可追溯资讯底座： + - 通过 owning YAML 管理 RSS、Atom、公开 API、Hacker News 和人工来源； - 保留一手来源、发现来源、信任层级、分类、版权提示和原始响应； - - 优先处理嵌入式与 AI、纯嵌入式、AI，并识别优惠、样片和免费额度等实用信息。 -- 编辑策划： - - 支持授权 LLM 和完全离线模板两种文稿路径； - - 生成固定开场、卡片大纲、分条口播、术语补充、总结、参考来源和评论区文案； + - 优先处理嵌入式与 AI、纯嵌入式、AI 和实用优惠信息。 +- 有效编辑策划： + - 提供授权 LLM 和完全离线模板两种文稿路径； + - 生成合并开场与卡片大纲、逐条口播、专业对象补充、参考来源和评论区文案； + - 最后一条资讯结束后直接进入参考来源，不生成总结场景； - 对状态、日期、数字、媒体归因、预印本和专业对象说明实施质量门。 -- 视觉制作： - - 采集来源网页或 GitHub 页面为本地视觉工件； - - 为生成内容输出暖色、圆角、可配置的 HTML 动效、PNG 预览和 PPTX； - - 以确定性时间驱动页面滚动、章节进度和阶段导航。 -- 音频成片： - - 使用本地开源中文 TTS 生成可缓存配音； - - 由 YAML 控制音色、语速、停顿、响度、字幕和编码； +- 可审查动态视觉： + - 采集实际来源网页、GitHub 页面或论文页面为本地视觉工件； + - 使用本地 OCR 和可审查的视觉规划选择信息充分的画面； + - 生成以白色和绿色为主、暖阳圆角、无渐变的 HTML 动效、PNG 预览和 PPTX； + - 以确定性时间驱动页面滚动、重点放大、章节进度和阶段导航。 +- 自然音频成片： + - 使用本地开源中文 TTS 生成可缓存、可替换音色和可调语速的配音； + - 由 owning YAML 管理音色、语速、停顿、响度、字幕和编码； - 生成 WAV、时间线、SRT、ASS、MP4、封面和自动检查报告。 -- 流水线平台： +- 可调试流水线平台： - TypeScript CLI 支持单步、区间和完整流水线； - 长任务采用异步作业，提供状态、进度、日志、结果、重试和取消； - - 同源 Web 编辑台展示期次、作业、日志、费用和已登记媒体工件； - - 当前工件清单是步骤输出索引，不是经过内容版本兼容性校验的完整发布包。 -- 发布运营： + - 同源 Web 编辑台展示期次、作业、日志、费用和全部已登记工件； + - 工件按内容版本兼容性组合为完整发布包。 +- 受控发布运营： - 生成与最终成片真实章节起点一致的评论区时间轴； - - 输出参考来源、公开目录价成本估算、技术验收结果和人工复核提示； + - 输出参考来源、公开目录价成本估算、技术验收结果和人工复核材料； + - 持久化批准人、批准时间、退回记录、发布版本和反馈台账； - 通过本地或公网 IP 提供候选成片和工件的受控预览。 +- 隔离自动交付： + - 提供 Web 内置 Codex 终端、版本化后端容器、会话 PVC 和重启自动恢复； + - 通过 YAML-first Kubernetes 投影相互隔离的 Secret，并从公网 IPv4 原入口验收； + - 建立 GitHub、mirror、PaC、Tekton、GitOps 和 Argo 自动交付链； + - Web 工厂与生成内容主题解耦，采用工业风和紧凑高信息密度布局。 -### 2.3 当前差距与目标边界 +### 2.3 终态验收边界 -- 当前没有持久化的人工批准状态、批准人、批准时间、退回记录或发布版本台账。 -- 当前没有把全部媒体、来源、费用和检查工件按内容版本兼容性组合成发布包。 -- 当前没有 Web 内置 Codex 终端、版本化后端容器、会话 PVC 或重启自动恢复。 -- 当前没有 YAML-first Kubernetes 部署、隔离 Secret 投影或公网 IP 部署后验收。 -- 当前没有 GitHub、mirror、PaC、Tekton、GitOps 和 Argo 自动交付链。 -- 当前 Web 编辑台仍需与生成内容主题解耦，目标控制台采用工业风和紧凑高信息密度布局。 -- 第 6 章使用“应”描述目标需求；目标要求不代表当前实现或当前上线状态。 +- 七个 L1 必须分别满足原入口验收，才能宣称 L0 终态达成。 +- 单机样片、一次成功作业、临时公网入口或部分步骤工件不能替代 L0 终态验收。 +- 自动技术检查通过不能替代人工事实、版权、听感、平台规则和发布批准。 +- 当前状态、实现差距和一次性证据只进入阶段报告、任务报告、偏离记录或执行 issue。 -### 2.4 长期愿景 +### 2.4 扩展目标 - 形成多栏目、多主题、多语言和多平台复用的内容生产模型，同时保持每个栏目独立的来源、策划、视觉、声音和发布策略。 - 让人工编辑能够在任何阶段插入、覆盖、重跑或批准结果，不被端到端自动化锁死。 @@ -115,7 +125,7 @@ | 一手来源 | 由产品、项目、公司、机构或作者团队直接发布的公告、发布说明、论文或仓库记录。 | | 发现来源 | 用于发现线索和提供编辑背景的媒体、社区或聚合入口，不替代可获得的一手事实。 | | 来源闭环 | 口播中的可核验事实能够解析到期次来源项，并在引用与发布材料中保持同一归因。 | -| 内容单元 | 开场、大纲、单条资讯、总结或参考来源等可独立配音和映射场景的结构化文稿单元。 | +| 内容单元 | 开场与大纲、单条资讯或参考来源等可独立配音并映射场景的结构化文稿单元。 | | 场景 | 具有独立画面、时间范围、章节标题和动效状态的视频组成单元。 | | 工件 | 流水线生成并登记的来源、文稿、视觉、音频、字幕、视频、报告或发布文本文件。 | | 发布候选 | 已通过自动技术检查但仍需人工事实、版权、听感和平台规则复核的成片及配套材料。 | @@ -245,7 +255,7 @@ flowchart TD 数据流中的每个正式步骤必须读取已登记上游工件并输出新工件。上游缺失或不合法时应明确失败，不得使用隐藏默认值、旧期次文件或伪造输入补成成功。 -图中的自动交付、目标发布包和持久化人工复核属于目标能力。当前只具备主机运行、步骤工件、评论区材料和技术检查。 +图中的自动交付、发布包和持久化人工复核都属于终态必需能力。 ### 5.3 关键时序图 @@ -283,21 +293,7 @@ sequenceDiagram 长任务必须异步执行。CLI 和 Web 提交后立即获得作业标识，编辑者通过状态、日志和工件观察进展；重试创建新作业并保留旧证据，不能覆盖失败历史。 -图中的自动交付、内置终端和批准记录属于目标时序；当前实现从创建期次到技术检查和候选预览的部分已经跑通。 - -### 5.4 当前实现映射 - -| 能力 | 当前实现引用 | 当前事实 | -| --- | --- | --- | -| 配置入口 | `/root/selfmedia/config/selfmedia.yaml` 及其 `configRefs` | YAML 是可调事实来源，配置缺失或不合法时失败。 | -| CLI 与作业 | `/root/selfmedia/scripts/selfmedia-cli.ts`、`scripts/src/jobs.ts`、`scripts/src/runner.ts` | 支持单步、完整流程、状态、日志、结果、重试和取消。 | -| 内容步骤 | `/root/selfmedia/scripts/src/steps/` | 已实现采集、文稿、视觉、幻灯、配音、字幕、渲染和检查。 | -| Web 编辑台 | `/root/selfmedia/scripts/src/server-app.ts`、`web/src/` | 同源展示期次、作业、用量和媒体工件。 | -| 期次事实 | `/root/selfmedia/data/editions//` | 来源、文稿、媒体、时间线、用量和检查结果按期次归档。 | -| 已验证样片 | `embedded-ai-weekly-2026-07-13-r3` | 已形成九场景、五条资讯、网页滚动、配音字幕、成片、评论区和十项技术检查。 | -| 发布状态 | 当前无持久化批准与发布台账 | 已生成候选和复核材料，但没有批准人、批准时间、退回或已发布状态。 | -| 发布包 | 当前无版本兼容性发布包 | 存在步骤工件和输出清单，但尚未按内容版本校验并组合全部发布材料。 | -| 平台交付 | 当前无正式 Kubernetes 运行面 | Web Codex、隔离会话、YAML-first K8s 和自动交付均为 [PJ2026-0207 平台交付](PJ2026-0207-platform-delivery.md) 目标。 | +自动交付、内置终端和批准记录都属于终态关键时序，不得以部分时序成功宣称整期或整个平台达成。 ## 6. 全局原子需求 @@ -325,11 +321,21 @@ sequenceDiagram | --- | --- | --- | --- | | SMF-L0-REQ-002 | 有效编辑叙事 | [PJ2026-0202 编辑策划](PJ2026-0202-editorial-planning.md) | [资讯源](PJ2026-0201-information-sources.md)、[视觉制作](PJ2026-0203-visual-production.md)、[音频成片](PJ2026-0204-audio-video-production.md)、[发布运营](PJ2026-0206-publishing-operations.md) | -智媒工厂应把来源证据转化为信息密度高、口语自然、对技术受众有实际价值的栏目文稿，并保持开场、概述、故事、总结和参考来源的稳定结构。 +智媒工厂应把来源证据转化为栏目文稿，并满足： + +- 信息密度高； +- 口语自然； +- 对技术受众有实际价值； +- 保持开场与大纲、逐条故事和参考来源的稳定结构。 编辑策划负责选题、事实边界、术语补充、媒体归因、状态限定和叙事节奏。下游模块只能消费结构化内容，不能以画面或配音修饰掩盖证据不足和文稿空泛。 -完成标准是：每条资讯说清“发生了什么、谁发布、对受众有什么影响、目前不能据此推出什么”，并能通过来源引用复核关键事实。 +完成标准如下： + +- 每条资讯说清“发生了什么、由谁发布、对象有什么功能、对受众有什么价值”； +- 关键事实能够通过来源引用复核； +- 事实边界在相关表述处自然说明； +- 不使用机械的局限、约束或验证建议收尾。 ### 6.3 SMF-L0-REQ-003 动态视觉表达 @@ -435,8 +441,8 @@ Web 工厂和控制台应采用工业风、紧凑高信息密度、直角或极 ### 7.2 实现引用和追溯 -- 本规格当前实现引用版本为 `draft-2026-07-13-p0`。 -- 后续新增或修改的源码文件应在可承载注释的文件头标记： +- 本规格实现引用版本为 `draft-2026-07-13-p0`。 +- 相关源码文件应在可承载注释的文件头标记： - `SPEC: PJ2026-02 智媒工厂 draft-2026-07-13-p0`； - 同时标记主责 L1 的编号、短名和实现引用版本。 - 自动生成文件、第三方文件、纯配置、锁文件和二进制工件可以不加文件头： @@ -489,5 +495,9 @@ Web 工厂和控制台应采用工业风、紧凑高信息密度、直角或极 ### 7.6 规格回写 - 稳定需求、边界或验收变化回写对应 L1；影响多个 L1 时同时更新本 L0 索引和全局数据流。 -- 实现细节、作业编号、日志、截图和长证据保留在项目运行工件，不写入稳定规格正文。 +- 执行态内容不写入稳定规格正文： + - 实现状态和阶段基线； + - 阻塞和实现细节； + - 源码路径、作业编号、日志、截图和长证据。 +- 执行态内容进入阶段报告、任务报告、偏离记录或执行 issue。 - 规格间只使用本目录内的相对链接；不在规格正文保存 GitHub issue 或 PR 链接。 diff --git a/project-management/PJ2026-02/specs/PJ2026-0201-information-sources.md b/project-management/PJ2026-02/specs/PJ2026-0201-information-sources.md index d71b1f4c..c7014941 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0201-information-sources.md +++ b/project-management/PJ2026-02/specs/PJ2026-0201-information-sources.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于现有公开 Feed、Hacker News API、人工来源和期次来源清单建立资讯源规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义公开 Feed、Hacker News、人工来源和期次来源清单的目标能力。 | ## 正文 @@ -19,13 +17,18 @@ | 编号 | PJ2026-0201 | | 短名 | 资讯源 | | 层级 | L1 方向 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只保留资讯发现、采集、证据、分类、排序和使用边界的稳定需求。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文只定义： + +- 资讯发现、采集、证据、分类、排序和使用边界的预期终态； +- 对应验收契约。 ## 2. 目的和范围 @@ -94,7 +97,7 @@ | PJ2026-020105 | 优惠信息 | 本规格 6.5 | 期限、地区、资格、条件、过期和返利边界 | 官方公告、人工核验 | 编辑策划、发布运营 | | PJ2026-020106 | 来源治理 | 本规格 6.6 | 归因、预印本、版权、失败和过期来源处置 | 全部来源环节 | 视觉制作、发布运营 | -本章图形描述目标数据面。当前已实现范围和未实现差距见第 7.1 节。 +本章图形描述资讯源的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -198,7 +201,7 @@ sequenceDiagram 没有稳定公开入口的来源应声明为 `manual-only`，不能在代码中私自增加隐藏抓取路径。 -当前基线覆盖： +来源目录至少应覆盖： - Arm、NXP、MicroPython、LVGL、Arm-2D 和 PikaPython； - NI、Analog Devices、ST、NVIDIA、Arduino 和嘉立创相关入口； @@ -252,7 +255,12 @@ sequenceDiagram | --- | --- | --- | --- | | SOURCE-L1-REQ-004 | 分类排序 | PJ2026-020104 分类排序 | [编辑策划](PJ2026-0202-editorial-planning.md) | -系统应按照栏目 owning YAML 对候选资讯分类和排序，当前优先顺序为嵌入式与 AI、纯嵌入式、AI，并在同类中优先一手来源、明确状态、近期发布和可行动价值。 +系统应按照栏目 owning YAML 对候选资讯分类和排序。 + +默认排序规则如下： + +- 依次优先嵌入式与 AI、纯嵌入式、AI； +- 同类中优先一手来源、明确状态、近期发布和可行动价值。 分类必须基于来源默认值和内容证据： @@ -298,21 +306,13 @@ sequenceDiagram ## 7. 过程控制 -### 7.1 当前实现状态与引用 +### 7.1 实现引用契约 -- 当前已经实现 YAML 来源目录、Feed/API/人工来源、原始响应、归一化、去重、分类排序和来源清单。 -- 当前已经在真实 R3 期次中采集第一方、国际媒体、Hacker News 和人工来源。 -- 第 6 章仍是稳定目标口径；新增来源、许可变化和优惠复核需要持续按该口径验收。 - -- 来源 owning YAML：`/root/selfmedia/config/sources.yaml`。 -- 栏目分类和排序：`/root/selfmedia/config/editorial.yaml`。 -- 采集与归一：`/root/selfmedia/scripts/src/steps/collect.ts`。 -- 期次输入与输出： - - `inputs/manual-sources.yaml`； - - `sources/raw/`； - - `sources/manifest.json`。 -- 后续相关源码修改应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0201 资讯源 draft-2026-07-13-p0`。 +- 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头： + - 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。 +- 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 原入口验收 diff --git a/project-management/PJ2026-02/specs/PJ2026-0202-editorial-planning.md b/project-management/PJ2026-02/specs/PJ2026-0202-editorial-planning.md index 16d86a77..15455fac 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0202-editorial-planning.md +++ b/project-management/PJ2026-02/specs/PJ2026-0202-editorial-planning.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于现有结构化文稿、质量门、专业对象补充和来源闭环建立编辑策划规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义结构化文稿、质量门、专业对象补充和来源闭环的目标能力。 | ## 正文 @@ -19,13 +17,18 @@ | 编号 | PJ2026-0202 | | 短名 | 编辑策划 | | 层级 | L1 方向 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义选题、事实核验、栏目结构、叙事和引用的稳定完成标准。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文只定义： + +- 选题、事实核验、栏目结构、叙事和引用的预期终态； +- 对应验收契约。 ## 2. 目的和范围 @@ -35,14 +38,14 @@ - 把可追溯来源转化为有判断、有信息密度、适合技术受众收听的栏目内容； - 决定本期为什么讲这些消息； -- 决定每条消息要解释到什么深度以及哪些限制必须明说； -- 让开场、大纲、故事和总结形成连贯叙事； +- 决定每条消息要解释到什么深度，并把必要事实边界放在相关表述处； +- 让开场与大纲、逐条故事和参考来源形成连贯叙事； - 避免把来源摘要机械拼接成“AI 味”文稿。 ### 2.2 范围内 - 栏目定位、受众假设、期次题目、候选池、选题数量和内容优先级。 -- 固定开场、五十字内概述、卡片大纲、单条故事、总结和参考来源口播结构。 +- 固定开场、五十字内概述、卡片大纲、单条故事和参考来源口播结构。 - 事实锚点、日期、数字、产品状态、媒体归因、预印本和活动条件的表达边界。 - 按受众熟悉度补充专业对象的功能、作者、公司、发布者或大学团队来源。 - 结构化文稿、配音文本、视觉方向、来源引用和评论区来源文本的内容一致性。 @@ -66,7 +69,7 @@ | 专业对象补充 | 对陌生库、组件、框架、协议或项目补充其功能和发布者的短句。 | | 状态限定 | 对 beta、预览、预印本、临时调整、媒体报道、地区限制等事实边界的明确表达。 | | 镜头意图 | 文稿为视觉制作提供的信息重点、来源页面和画面节奏建议，不是最终视觉实现。 | -| 结构化文稿 | 包含开场、大纲、故事、总结、参考来源、配音单元和来源引用关系的机器可读工件。 | +| 结构化文稿 | 包含开场与大纲、故事、参考来源、配音单元和来源引用关系的机器可读工件。 | | 模板模式 | 不调用 LLM、根据来源和固定规则生成可调试文稿的离线路径。 | ## 4. 系统边界和接口 @@ -78,7 +81,7 @@ | 外部使用者 | 栏目编辑、审核者、视觉制作、音频成片和发布运营。 | | 外部输入 | 期次元数据、来源候选池、栏目规则、受众熟悉对象、人工编辑意见和可选 LLM 响应。 | | 受控资源 | 选题结果、结构化文稿、质量门反馈、配音单元、镜头意图、来源引用和引用目录。 | -| 外部输出 | 开场、大纲、故事、总结、参考来源口播、配音文本、视觉方向和可解析引用。 | +| 外部输出 | 开场与大纲、故事、参考来源口播、配音文本、视觉方向和可解析引用。 | | 用户接口 | TypeScript CLI 文稿单步、可编辑 JSON/TXT/Markdown 工件、日志和 Web 文稿视图。 | | 系统边界 | 编辑策划负责“说什么以及如何准确地说”；不负责来源可访问性、画面制作、声音表现和最终发布批准。 | @@ -88,12 +91,12 @@ | --- | --- | --- | --- | --- | --- | | PJ2026-020201 | 栏目策划 | 本规格 6.1 | 栏目定位、受众、期次结构和选题组合 | 期次元数据、来源候选 | 全部编辑环节 | | PJ2026-020202 | 事实核验 | 本规格 6.2 | 锚点、状态、数字、日期、归因和不能推出的结论 | 资讯源 | 文稿生成、发布复核 | -| PJ2026-020203 | 口播叙事 | 本规格 6.3 | 开场、大纲、故事、总结、节奏和语言质量 | 栏目策划、事实核验 | 视觉制作、音频成片 | +| PJ2026-020203 | 口播叙事 | 本规格 6.3 | 开场与大纲、故事、来源转场、节奏和语言质量 | 栏目策划、事实核验 | 视觉制作、音频成片 | | PJ2026-020204 | 对象补充 | 本规格 6.4 | 专业对象功能、作者或发布者说明与熟悉对象免补充 | 事实核验、受众规则 | 口播叙事 | | PJ2026-020205 | 文稿质量 | 本规格 6.5 | 生成、重试、质量门、模板路径和人工覆盖 | 全部编辑环节 | 流水线平台 | | PJ2026-020206 | 引用闭环 | 本规格 6.6 | 文稿到来源、镜头、配音和发布引用的一致关系 | 资讯源、结构化文稿 | 发布运营 | -本章图形描述目标数据面。当前已实现范围和未实现差距见第 7.1 节。 +本章图形描述编辑策划的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -134,7 +137,7 @@ flowchart TD Pool[可追溯候选池] --> Select[按价值与组合选题] Select --> Evidence[提取事实锚点与限制] Evidence --> Audience[判断受众熟悉度] - Audience --> Draft[生成开场 / 大纲 / 故事 / 总结] + Audience --> Draft[生成开场与大纲 / 故事 / 来源转场] Draft --> Gate[结构、证据与语言质量门] Gate -->|拒绝并反馈| Draft Gate -->|接受| Script[结构化文稿] @@ -196,7 +199,7 @@ sequenceDiagram 系统不得只选择得分最高或标题最热的若干条。 -当前栏目组合规则如下： +默认栏目组合规则如下： - 优先嵌入式与 AI 交叉； - 其次纯嵌入式； @@ -217,9 +220,15 @@ sequenceDiagram 具体事实使用规则如下： - 日期、版本、处理器、内存、价格、性能和截止时间只有在证据明确时才能出现； -- 来源未提供延迟、功耗、精度、兼容性或开放范围时，文稿应说明未知； +- 来源未提供延迟、功耗、精度、兼容性或开放范围时，不得编造相关结论； - 不能用行业常识填成该产品事实。 +事实边界表达应满足： + +- 必要的状态或适用范围放在相关事实附近； +- 不在每条故事末尾机械添加局限、约束、限制或风险； +- 不使用“仍需验证”类固定收尾句。 + 媒体报道必须说“媒体报道”或点明媒体；大学论文只有在来源明确单位时才说“来自某大学团队”，否则使用“作者团队”；预印本不得暗示已经同行评审。 ### 6.3 EDIT-L1-REQ-003 固定栏目结构 @@ -228,12 +237,13 @@ sequenceDiagram | --- | --- | --- | --- | | EDIT-L1-REQ-003 | 口播结构 | PJ2026-020203 口播叙事 | [视觉制作](PJ2026-0203-visual-production.md)、[音频成片](PJ2026-0204-audio-video-production.md) | -系统应生成稳定但不僵硬的栏目结构，至少包含开场、卡片式大纲、逐条资讯、总结和参考来源口播。 +系统应生成稳定但不僵硬的栏目结构，至少包含合并的开场与卡片式大纲、逐条资讯和参考来源口播。 开场应使用期次元数据确定性生成： - 报出期数、栏目名和日期； - 使用“主要内容有”引出不超过五十字的概述； +- 在同一开场场景中展示卡片式大纲； - 使用“下面是详细内容”进入正文； - 不允许 LLM 改写期数、日期或固定句式。 @@ -241,8 +251,8 @@ sequenceDiagram - 每条故事先给核心变化； - 再解释技术或业务影响； -- 最后说明限制、验证建议或下一步； -- 总结收束共同主题，不重复逐条摘要； +- 以正面、具体、可核验的功能、行动价值或后续动向自然收束； +- 最后一条故事结束后直接进入参考来源，不生成总结段或总结场景； - 参考来源口播固定为“以下是这期《栏目名》的参考来源，完整链接见评论区”。 ### 6.4 EDIT-L1-REQ-004 受众适配说明 @@ -279,6 +289,7 @@ sequenceDiagram - 固定结构、概述长度和故事数量； - 引用可解析、事实锚点和状态限定； - 专业对象补充、空泛套话和后台术语； +- 机械的局限、约束、限制、风险或“仍需验证”类结尾； - 不适合口播的格式。 失败时应保存拒绝原因，并把具体反馈用于下一次尝试。 @@ -303,32 +314,23 @@ sequenceDiagram ## 7. 过程控制 -### 7.1 当前实现状态与引用 +### 7.1 实现引用契约 -- 当前已经实现授权 LLM、模板模式、确定性开场、质量门、专业对象补充、引用和配音单元。 -- 当前 R3 文稿已经生成开场、大纲、五条故事、总结和参考来源口播。 -- 第 6 章描述持续目标；人工批准和发布版本不由本 L1 当前实现提供。 - -- 栏目和文稿 owning YAML：`/root/selfmedia/config/editorial.yaml`。 -- 文稿生成与质量门：`/root/selfmedia/scripts/src/steps/script.ts`。 -- 评论区来源：`/root/selfmedia/scripts/src/comment-reference.ts`。 -- 期次工件： - - `script/episode.json`； - - `script/narration.txt`； - - `script/citations.md`； - - `script/comment-reference.txt`。 -- 后续相关源码修改应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0202 编辑策划 draft-2026-07-13-p0`。 +- 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头： + - 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。 +- 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 原入口验收 - 通过 TypeScript CLI 单步运行 `script`： - 授权 LLM 路径应记录模型、请求和用量工件； - `--template-only` 路径应不读取 LLM 凭据。 -- 核对开场期数、栏目名、日期、五十字内概述和固定转场句。 +- 核对开场期数、栏目名、日期、五十字内概述、卡片大纲和固定转场句。 - 核对每条故事的事实锚点、来源角色、状态限定、专业对象补充和未知信息边界。 - 核对引用可在期次来源清单中解析，配音单元和故事顺序一致。 -- 通过人工朗读抽检口语节奏、信息密度和“AI 味”套话。 +- 通过人工朗读抽检口语节奏、信息密度、“AI 味”套话和机械限制型结尾。 ### 7.3 质量门和人工覆盖 diff --git a/project-management/PJ2026-02/specs/PJ2026-0203-visual-production.md b/project-management/PJ2026-02/specs/PJ2026-0203-visual-production.md index 9fc3da94..6da24f33 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0203-visual-production.md +++ b/project-management/PJ2026-02/specs/PJ2026-0203-visual-production.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于来源页面视觉、暖色 HTML 动效、九阶段导航、PNG 和 PPTX 能力建立视觉制作规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义来源页面视觉、HTML 动效、阶段导航、PNG 和 PPTX 的目标能力。 | ## 正文 @@ -19,13 +17,18 @@ | 编号 | PJ2026-0203 | | 短名 | 视觉制作 | | 层级 | L1 方向 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义来源视觉、场景、主题、动效、演示文稿和视觉验收的稳定需求。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文只定义： + +- 来源视觉、场景、主题、动效、演示文稿和视觉验收的预期终态； +- 对应验收契约。 ## 2. 目的和范围 @@ -35,14 +38,16 @@ - 把结构化文稿和来源证据转化为信息清楚、节奏连贯的动态画面； - 形成具有栏目辨识度的视觉语言； -- 生成的 HTML、PPT、PNG、封面和视频采用温暖、阳光、圆润的科技编辑部方向； +- 生成的 HTML、PPT、PNG、封面和视频采用白色与绿色为主、温暖、阳光、圆润的科技编辑部方向； - 避免冷冽的蓝黑仪表盘观感； -- 长期支持栏目主题切换，同时保持来源可追溯、绝对时间可复现和多工件一致。 +- 支持栏目主题切换，同时保持来源可追溯、绝对时间可复现和多工件一致。 ### 2.2 范围内 - 入选资讯原始网页、GitHub 页面或论文摘要页的本地视觉采集和失败降级。 -- 开场、卡片大纲、逐条资讯、总结和参考来源等场景类型。 +- 合并开场与卡片大纲、逐条资讯和参考来源等场景类型。 +- 本地开源 OCR、画面信息量分析、LLM 画面筛选和可审查的重点区域规划。 +- Web 人工调整重点区域、出现时段和放大比例的控制入口。 - YAML 可配置的色彩、圆角、阴影、纹理、字号、留白、字幕安全区和章节导航。 - HTML/CSS/JavaScript 动效、来源页面向下滚动、绝对时间寻址和逐帧渲染状态。 - 顶部阶段内细进度、底部总阶段导航和总进度的对齐与跳转语义。 @@ -70,7 +75,9 @@ | 绝对时间寻址 | 通过场景内毫秒位置直接计算动效状态，使任意帧可重现而不依赖前序播放。 | | 阶段内进度 | 位于画面顶部、表示当前场景内部播放位置的细进度条。 | | 总阶段导航 | 位于画面底部、等宽等高展示整期短标题并与总进度 X 轴对齐的章节导航。 | -| 来源滚动 | 在若干本地来源帧之间按绝对时间确定性过渡，形成页面向下滚动的视觉效果。 | +| 来源滚动 | 单个页面按绝对时间从上到下滚动，完成后直接切换下一页面的确定性视觉效果。 | +| OCR 画面证据 | 本地开源 OCR 从候选画面提取的文本、位置、布局和置信度，用于筛选与重点区域验证。 | +| 重点区域 | 在来源画面中可由 OCR 和来源事实验证，或由编辑者手工指定的放大矩形、出现时段和倍率。 | | 内容主题令牌 | 由 YAML 管理的生成内容颜色、圆角、阴影、纹理和布局参数。 | | 字幕安全区 | 为字幕和播放器覆盖层预留、不得放置关键信息的画面区域。 | | 无图降级 | 来源页面不可采集或不适合使用时，以原创文字、数据卡片和来源标识替代第三方画面。 | @@ -92,14 +99,14 @@ | 编号 | 模块或课题 | 规格位置 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | -| PJ2026-020301 | 来源画面 | 本规格 6.1 | 页面采集、滚动位置、清单、失败和无图降级 | 资讯源、结构化文稿 | 场景编排 | -| PJ2026-020302 | 场景编排 | 本规格 6.2 | 开场、大纲、故事、总结、来源页和章节身份 | 编辑策划、来源画面 | 动效渲染、音频成片 | +| PJ2026-020301 | 来源画面 | 本规格 6.1 | 页面采集、OCR、画面筛选、滚动位置、清单、失败和无图降级 | 资讯源、结构化文稿 | 场景编排 | +| PJ2026-020302 | 场景编排 | 本规格 6.2 | 开场与大纲、故事、来源页和章节身份 | 编辑策划、来源画面 | 动效渲染、音频成片 | | PJ2026-020303 | 主题系统 | 本规格 6.3 | 色彩、圆角、阴影、纹理、字号、留白和主题切换 | YAML、栏目定位 | 全部场景 | | PJ2026-020304 | 导航进度 | 本规格 6.4 | 阶段内进度、总导航、总进度、对齐和标题高度 | 场景编排、时间线 | 成片、Web 跳转 | -| PJ2026-020305 | 动效渲染 | 本规格 6.5 | 绝对时间寻址、来源滚动、逐帧一致性和离线渲染 | 场景编排、主题系统 | 音频成片 | +| PJ2026-020305 | 动效渲染 | 本规格 6.5 | 绝对时间寻址、来源滚动、重点放大、逐帧一致性和离线渲染 | 场景编排、主题系统 | 音频成片 | | PJ2026-020306 | 视觉工件 | 本规格 6.6 | HTML、PNG、PPTX、封面和视觉质量边界 | 全部视觉环节 | 发布运营 | -本章图形描述目标数据面。当前已实现范围和未实现差距见第 7.1 节。 +本章图形描述视觉制作的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -113,13 +120,19 @@ flowchart LR subgraph VisualPlane[视觉制作数据面] Capture[来源页面采集器] VisualStore[本地来源帧与清单] + OCR[本地 OCR] + Planner[画面筛选与重点规划] SceneCompiler[场景编排器] HtmlRenderer[HTML 动效渲染器] DeckRenderer[PNG / PPTX 渲染器] end Sources --> Capture Capture --> VisualStore + VisualStore --> OCR + OCR --> Planner Script --> SceneCompiler + Script --> Planner + Planner --> SceneCompiler VisualStore --> SceneCompiler Theme --> SceneCompiler SceneCompiler --> HtmlRenderer @@ -137,7 +150,9 @@ flowchart TD Script[结构化文稿] --> Scenes[场景编排] Sources[来源清单] --> Capture[来源页面采集] Capture --> VisualManifest[来源视觉清单] - VisualManifest --> Scenes + VisualManifest --> OCR[本地 OCR 与布局] + OCR --> Plan[画面筛选与重点区域计划] + Plan --> Scenes Theme[主题 owning YAML] --> HTML[HTML 场景生成] Scenes --> HTML HTML --> Preview[PNG 预览] @@ -189,6 +204,31 @@ sequenceDiagram 系统应为每条入选资讯按来源视觉策略采集本地画面，并在视觉清单中保留故事、来源、链接、页面标题、采集状态、画面路径、滚动位置、页面高度和失败原因。 +候选画面必须经过本地开源 OCR，至少登记： + +- 识别文本、文本框、行和布局； +- 置信度、画面尺寸和 OCR 模型版本； +- 可与来源事实匹配的关键词和重点区域候选。 + +授权 LLM 可以消费： + +- OCR 结果； +- 来源事实； +- 候选画面摘要。 + +LLM 输出应包含： + +- 画面选择和理由； +- 重点矩形； +- 出现时段； +- 放大倍率。 + +自动重点放大应满足： + +- 只有 OCR 或来源事实能够验证时才能生效； +- 置信不足时标记为人工确认； +- 允许编辑者在 Web 中手工调整。 + 来源画面可以按网页、GitHub 和论文摘要使用不同样式，但必须遵守： - 来自实际采用的公开来源； @@ -206,16 +246,15 @@ sequenceDiagram 系统应把结构化文稿编排为具有稳定身份和章节语义的场景： -- 当前栏目至少包含封面开场、卡片大纲、每条资讯、总结和参考来源； +- 栏目至少包含合并的开场与卡片大纲、每条资讯和参考来源； - 故事数量变化时，场景数量应按内容生成； - 场景数量不能写死为九页。 各场景职责如下： -- 开场突出期数、日期和主题； -- 大纲使用可快速扫读的卡片； +- 开场突出期数、日期和主题，并在同一场景使用可快速扫读的卡片大纲； - 故事页呈现短标题、核心变化、关键信息和来源画面； -- 总结收束主题； +- 最后一条故事结束后直接进入参考来源； - 参考来源页以类似参考文献的编号格式列出实际采用来源。 场景标题、章节短标题、中文短释和来源身份应来自同一结构化文稿，不允许在 HTML、PPTX 和视频中分别人工维护。 @@ -226,7 +265,15 @@ sequenceDiagram | --- | --- | --- | --- | | VISUAL-L1-REQ-003 | 暖阳主题 | PJ2026-020303 主题系统 | [编辑策划](PJ2026-0202-editorial-planning.md)、[发布运营](PJ2026-0206-publishing-operations.md) | -系统应通过 owning YAML 管理生成内容主题令牌。当前默认主题使用米白、琥珀、陶土和暖棕色，大圆角、柔和阴影和轻纸纹营造温暖、阳光的编辑部感受。 +系统应通过 owning YAML 管理生成内容主题令牌。 + +默认主题应满足： + +- 以纯白为大面积底色； +- 以中深绿色作为框线、点缀、导航和装饰； +- 通过暖白、圆角、克制阴影和充分留白营造温暖、阳光的编辑部感受。 + +默认主题不得使用渐变。页面层级应通过边框、色块、字号、间距和少量实色强调建立，不得用大面积渐变制造科技感。 本主题只用于生成的 HTML、PPT、PNG、封面和视频。Web 工厂、控制台与内置终端不得继承这些大圆角、卡片留白和暖色装饰规则。 @@ -237,7 +284,7 @@ sequenceDiagram - 不让暖色退化为所有元素同色； - 不依赖颜色单独表达状态。 -主题切换不得改变场景数据、来源关系和时间线契约。未来栏目可以有其他主题，但生产 HTML 不得依赖在线字体、脚本或样式服务。 +主题切换不得改变场景数据、来源关系和时间线契约。其他栏目可以选择不同主题，但生产 HTML 不得依赖在线字体、脚本或样式服务。 ### 6.4 VISUAL-L1-REQ-004 对齐章节导航 @@ -255,11 +302,20 @@ sequenceDiagram 阶段导航必须满足： - 所有阶段等宽、等高； +- 底部总览使用直角并与画面底边贴合； +- 相邻阶段之间不留空隙； +- X 轴从画面最左侧延伸到最右侧，并与总进度起止位置完全对齐； - 导航内只显示简短标题； - 标题过长时允许换行，并统一增加全部阶段的 Y 轴高度； - 不能截断、使用省略号或让单个阶段独自变高； - 标题长度和导航最大高度由配置给出上限。 +底部总览颜色应满足： + +- 过去、当前和未来阶段使用具有足够对比度的实色； +- 当前阶段和已完成阶段在典型视频压缩和普通显示器上仍可清楚区分； +- 不使用过浅底色。 + 场景数量和标题来自当期场景模型。HTML 预览和 Web 编辑台可以点击章节跳转，成片中的导航则以高亮和进度提供同一视觉语义。 ### 6.5 VISUAL-L1-REQ-005 确定性动态画面 @@ -270,7 +326,21 @@ sequenceDiagram 系统应以场景内绝对时间计算所有生产动效，使从任意时间点渲染的画面与从头播放到该点的画面一致。 -来源页面滚动应使用本地采集帧和确定性插值形成向下浏览效果。进场、强调、进度和卡片动效应服务信息理解，不能造成文字晃动、阅读时间不足或字幕冲突。 +来源页面滚动顺序如下： + +- 先直接显示一个页面； +- 在该页面内从上到下滚动； +- 滚动完成后直接切换到下一页面； +- 页面之间不得使用会让两页文字叠加的慢渐变。 + +重点放大应满足： + +- 使用视觉计划中的矩形、时段和倍率； +- 保持右侧来源画面文字可读； +- 自动计划未通过 OCR 或来源事实验证时不得静默启用； +- 使用 Web 人工调整结果或保持未放大画面。 + +进场、强调、进度和卡片动效应服务信息理解，不能造成文字晃动、阅读时间不足或字幕冲突。 浏览器渲染必须在禁用后台网络依赖的生产环境中运行。指定画布、捕获帧率和时间点应产生稳定尺寸与场景身份；中断重跑不得因上次浏览器状态改变结果。 @@ -293,28 +363,23 @@ sequenceDiagram ## 7. 过程控制 -### 7.1 当前实现状态与引用 +### 7.1 实现引用契约 -- 当前已经实现来源页面采集、无图降级、暖色 HTML 动效、PNG、PPTX 和双层进度导航。 -- 当前 R3 已生成九个场景和入选资讯的本地滚动页面帧。 -- 第 6 章描述稳定目标；多栏目主题治理和正式素材授权台账仍需后续实现。 - -- 主题与场景配置：`/root/selfmedia/config/editorial.yaml`、`config/tools.yaml`。 -- 来源视觉采集：`/root/selfmedia/scripts/src/steps/visuals.ts`。 -- 场景和演示文稿：`/root/selfmedia/scripts/src/steps/slides.ts`。 -- HTML 生成与浏览器渲染： - - `/root/selfmedia/scripts/src/slide-html.ts`； - - `/root/selfmedia/scripts/src/slide-browser.ts`。 -- 期次工件：`visuals/`、`slides/html/`、`slides/png/`、`slides/deck.pptx`、`output/cover.png`。 -- 后续相关源码修改应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0203 视觉制作 draft-2026-07-13-p0`。 +- 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头： + - 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。 +- 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 原入口验收 - 通过 TypeScript CLI 分别单步运行来源视觉和幻灯步骤。 - 核对每条入选资讯的视觉状态、来源链接、帧数、滚动位置和失败降级。 -- 在浏览器中检查开场、大纲、至少两条故事、总结和来源页的开始、中间、结束状态。 +- 在浏览器中检查合并开场与大纲、至少两条故事和来源页的开始、中间、结束状态。 +- 核对 OCR 文本和布局、LLM 画面选择理由、自动重点区域验证与 Web 人工调整结果。 - 检查顶部细进度、底部总导航、总进度 X 轴对齐、阶段等宽等高和长标题换行。 +- 检查底部总览直角贴边、阶段无间隙、全宽对齐和深色对比度。 +- 检查单页向下滚动完成后直接切页，页面之间不存在慢渐变文字重叠。 - 核对 HTML、PNG、PPTX 的场景数、顺序、尺寸、标题和来源一致。 - 在桌面和窄屏 Web 入口检查章节导航可点击且无横向溢出。 diff --git a/project-management/PJ2026-02/specs/PJ2026-0204-audio-video-production.md b/project-management/PJ2026-02/specs/PJ2026-0204-audio-video-production.md index 24e7fd1f..440f890f 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0204-audio-video-production.md +++ b/project-management/PJ2026-02/specs/PJ2026-0204-audio-video-production.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于本地 Kokoro 配音、可调语速、字幕时间线、FFmpeg 成片和自动检查建立音频成片规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义本地配音、可调语速、字幕时间线、成片和自动检查的目标能力。 | ## 正文 @@ -19,13 +17,18 @@ | 编号 | PJ2026-0204 | | 短名 | 音频成片 | | 层级 | L1 方向 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义本地配音、时间线、字幕、音视频合成和媒体质量的稳定需求。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文只定义： + +- 本地配音、时间线、字幕、音视频合成和媒体质量的预期终态； +- 对应验收契约。 ## 2. 目的和范围 @@ -60,7 +63,7 @@ | 术语 | 定义 | | --- | --- | -| 配音单元 | 与开场、大纲、故事、总结或来源场景对应的结构化可朗读文本。 | +| 配音单元 | 与开场和大纲、故事或来源场景对应的结构化可朗读文本。 | | 原始语音缓存 | 按文本、模型、音色和缓存版本索引的 TTS 原始推理结果。 | | 后处理语速 | 在原始 TTS 输出后以确定倍率调整时长的音频处理参数。 | | 句级时间线 | 每个配音分段的场景身份、开始、结束、停顿和音频路径记录。 | @@ -93,7 +96,7 @@ | PJ2026-020405 | 媒体检查 | 本规格 6.5 | 流、尺寸、时长、响度、峰值、解码和工件完整性 | 全部媒体环节 | 发布运营 | | PJ2026-020406 | 媒体重跑 | 本规格 6.6 | 参数影响范围、缓存复用和单步重新生成 | 流水线平台 | 编辑调试 | -本章图形描述目标数据面。当前已实现范围和未实现差距见第 7.1 节。 +本章图形描述音频成片的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -196,7 +199,22 @@ sequenceDiagram - 不改写事实或把技术标识变成错误词义； - 在读音不确定时提供人工词表或改稿入口。 -声音选择应优先自然、清晰和有轻微表现力，避免长篇机械平读。系统应允许未来替换更新的本地模型，但模型许可、文件哈希、运行资源和音色兼容性必须可复核。 +声音选择应满足： + +- 自然、清晰并具有轻微表现力； +- 避免长篇机械平读； +- 允许替换更新的本地模型； +- 模型许可、文件哈希、运行资源和音色兼容性可复核。 + +默认后处理语速应为所选模型自然基线的 `1.2x`，并允许通过 owning YAML 调整。 + +修改语速后只重跑： + +- 配音后处理； +- 时间线； +- 字幕； +- 渲染； +- 检查。 ### 6.2 MEDIA-L1-REQ-002 精确音频时间线 @@ -270,20 +288,13 @@ sequenceDiagram ## 7. 过程控制 -### 7.1 当前实现状态与引用 +### 7.1 实现引用契约 -- 当前已经实现本地 Kokoro 配音、缓存、可调语速、响度、句级时间线、SRT/ASS、FFmpeg 成片和十项技术检查。 -- 当前检查结果只说明媒体技术门槛通过，不提供事实、版权或发布批准状态。 -- 第 6 章描述可替换模型和持续媒体质量的目标口径。 - -- 媒体 owning YAML：`/root/selfmedia/config/tools.yaml`。 -- 配音：`/root/selfmedia/scripts/src/steps/voice.ts`、`tools/kokoro_tts.py`。 -- 字幕：`/root/selfmedia/scripts/src/steps/subtitles.ts`。 -- 渲染：`/root/selfmedia/scripts/src/steps/render.ts`、`scripts/src/slide-browser.ts`。 -- 检查：`/root/selfmedia/scripts/src/steps/inspect.ts`。 -- 期次工件：`audio/`、`subtitles/`、`output/episode.mp4`、`output/scene-timeline.json`、`output/inspection.json`。 -- 后续相关源码修改应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0204 音频成片 draft-2026-07-13-p0`。 +- 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头： + - 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。 +- 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 原入口验收 diff --git a/project-management/PJ2026-02/specs/PJ2026-0205-pipeline-platform.md b/project-management/PJ2026-02/specs/PJ2026-0205-pipeline-platform.md index b360f3ec..4eb19378 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0205-pipeline-platform.md +++ b/project-management/PJ2026-02/specs/PJ2026-0205-pipeline-platform.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于 YAML-first、TypeScript CLI、异步作业、用量计费和 Web 编辑台建立流水线平台规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义 YAML-first、TypeScript CLI、异步作业、用量计费和 Web 编辑台的目标能力。 | ## 正文 @@ -19,13 +17,13 @@ | 编号 | PJ2026-0205 | | 短名 | 流水线平台 | | 层级 | L1 方向 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义配置、调度、作业、工件、计量和可视控制面的稳定运行能力。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义配置、调度、作业、工件、计量和可视控制面的预期终态与验收契约。 ## 2. 目的和范围 @@ -96,7 +94,7 @@ | PJ2026-020505 | 用量成本 | 本规格 6.5 | LLM 请求用量、公开目录价、质量门结果和汇总 | 编辑策划、价格 YAML | CLI、Web、发布复核 | | PJ2026-020506 | 可视控制 | 本规格 6.6 | 同源 API、Web、媒体预览、服务生命周期和公网入口 | 作业事实、工件事实 | 编辑者和审核者 | -本章图形描述目标数据面。当前已实现范围和未实现差距见第 7.1 节。 +本章图形描述流水线平台的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -198,7 +196,7 @@ Secret 只允许通过受控引用在运行时读取，计划输出不得显示 系统应把以下能力定义为正式步骤： -- 采集、文稿、来源视觉和幻灯； +- 采集、文稿、来源视觉、本地 OCR、画面规划和幻灯； - 配音、字幕、渲染和检查。 每个步骤必须有明确上游工件、下游工件、进度、日志、结果和失败契约，并可以通过 TypeScript CLI 独立运行。 @@ -287,6 +285,22 @@ Web 工厂和控制台应采用工业风视觉： - 克制的状态色和低装饰背景； - 不复用生成内容的暖色大圆角、纸纹和宽松卡片布局。 +单步执行卡片应满足： + +- 只展示步骤信息和状态； +- 卡片本身不得触发运行； +- 每张卡片提供独立运行按钮； +- 点击运行按钮后弹出确认框； +- 确认框明确期次、步骤和预期覆盖范围后才能提交作业。 + +Web 应提供视觉计划审查入口。 + +自动重点区域不能由 OCR 或来源事实验证时，编辑者可以： + +- 手工调整矩形； +- 手工调整出现时段和放大倍率； +- 单步重跑幻灯或渲染。 + 音频和视频工件应支持 HTTP Range 以便拖动预览。Web 应在桌面和窄屏可用，不以颜色单独表达状态，不依赖外部字体、分析脚本或付费生成服务。 服务入口要求如下： @@ -294,30 +308,18 @@ Web 工厂和控制台应采用工业风视觉： - 监听、端口、轮询和健康超时由 owning YAML 配置； - 公网 IPv4 直连只能用于临时验收； - 明文 HTTP 且无鉴权时必须明确风险； -- 长期公开服务应独立规划 TLS、访问控制和发布权限； +- 持续公开服务应由对应规格明确 TLS、访问控制和发布权限； - 不能把临时公网入口默认升级为多用户生产服务。 ## 7. 过程控制 -### 7.1 当前实现状态与引用 +### 7.1 实现引用契约 -- 当前已经实现 YAML 配置、TypeScript CLI、单步/区间/完整流水线、异步作业、用量费用和同源 Web。 -- 当前工件索引登记步骤输出，但尚未提供跨重跑内容版本兼容性校验和完整发布包。 -- 当前服务是主机进程和临时公网 IPv4 预览，不等价于 [平台交付](PJ2026-0207-platform-delivery.md) 目标运行面。 -- 当前 Web 样式仍需按工业控制台边界收敛；生成媒体的暖色圆角主题不应继续支配控制面。 - -- 配置入口和校验： - - `/root/selfmedia/config/selfmedia.yaml`； - - `/root/selfmedia/scripts/src/config.ts`。 -- CLI、作业和调度： - - `/root/selfmedia/scripts/selfmedia-cli.ts`； - - `/root/selfmedia/scripts/src/jobs.ts`； - - `/root/selfmedia/scripts/src/runner.ts`。 -- 用量和价格：`/root/selfmedia/scripts/src/llm-usage.ts`、`config/pricing.yaml`。 -- 服务和 Web：`/root/selfmedia/scripts/src/server-app.ts`、`scripts/src/server-lifecycle.ts`、`web/src/`。 -- 作业事实：`/root/selfmedia/.state/jobs/`、`.state/results/`、`logs/`。 -- 后续相关源码修改应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0205 流水线平台 draft-2026-07-13-p0`。 +- 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头： + - 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。 +- 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 原入口验收 @@ -329,6 +331,8 @@ Web 工厂和控制台应采用工业风视觉： - 新作业具有不同标识； - 不产生半写正式工件。 - 构建并启动同源 Web，检查桌面、窄屏、媒体 Range、章节跳转、用量、费用和全部工件。 +- 验证步骤卡片本身不可点击，独立运行按钮提交前出现确认框。 +- 验证视觉计划可审查，低置信重点区域可以手工调整并单步重跑。 ### 7.3 安全和运行控制 diff --git a/project-management/PJ2026-02/specs/PJ2026-0206-publishing-operations.md b/project-management/PJ2026-02/specs/PJ2026-0206-publishing-operations.md index f08c02d0..b7eb0d43 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0206-publishing-operations.md +++ b/project-management/PJ2026-02/specs/PJ2026-0206-publishing-operations.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 基于技术检查、真实章节时间轴、评论区来源和公网预览建立发布运营规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义技术检查、真实章节时间轴、评论区来源和公网预览的目标能力。 | ## 正文 @@ -19,13 +17,18 @@ | 编号 | PJ2026-0206 | | 短名 | 发布运营 | | 层级 | L1 方向 | -| 状态 | 已生效 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义发布候选、时间轴、引用、人工批准、预览、归档和反馈回流的稳定需求。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文只定义： + +- 发布候选、时间轴、引用、人工批准、预览、归档和反馈回流的预期终态； +- 对应验收契约。 ## 2. 目的和范围 @@ -46,7 +49,7 @@ - 最终参考来源、媒体归因、AI 参与披露、公开成本提示和人工复核清单。 - 事实、版权、听感、视觉、优惠期限、平台规则和发布权限的人工批准或退回。 - 本地或公网 IP 预览、媒体拖动、工件访问和临时验收风险提示。 -- 期次版本留存、发布状态、纠错、撤回、再生成和匿名化反馈回流的长期愿景。 +- 期次版本留存、发布状态、纠错、撤回、再生成和匿名化反馈回流。 ### 2.3 范围外 @@ -79,7 +82,7 @@ | 外部输入 | 最终 MP4、封面、字幕、场景时间线、结构化文稿、来源清单、用量、检查报告和人工决定。 | | 受控资源 | 发布包、评论区文本、批准状态、退回原因、版本索引、纠错记录和反馈摘要。 | | 外部输出 | 可发布候选、时间轴、参考来源、披露、审核结论、平台预览和回流建议。 | -| 用户接口 | Web 编辑台、文件工件、媒体播放器、发布复核清单和未来平台适配器。 | +| 用户接口 | Web 编辑台、文件工件、媒体播放器、发布复核清单和受控平台适配器。 | | 系统边界 | 发布运营负责“是否具备发布条件以及发布什么版本”；实际平台账户操作仍由授权发布者负责。 | ## 5. 内部分工与下级索引 @@ -93,7 +96,7 @@ | PJ2026-020605 | 预览交付 | 本规格 6.5 | 本地/公网预览、媒体访问和临时入口风险 | 流水线平台 | 审核者 | | PJ2026-020606 | 版本反馈 | 本规格 6.6 | 版本、纠错、撤回、再生成和匿名反馈回流 | 发布决定、平台结果 | 全部 L1 改进 | -本章图形描述目标数据面。当前实现尚未提供持久化批准状态、兼容性发布包或反馈台账；已实现范围和目标差距见第 7.1 节。 +本章图形描述发布运营的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -169,7 +172,7 @@ sequenceDiagram end ``` -时序图描述目标能力。当前只能生成候选、时间轴、来源和检查材料，尚不能持久化批准人、批准时间或发布状态。 +时序图中的批准人、批准时间、退回原因和发布状态都必须持久化，并与候选版本和工件哈希关联。 ## 6. 原子需求 @@ -203,7 +206,7 @@ sequenceDiagram - 短标题和短释来自结构化文稿； - 时间来自最终场景； - 不使用按字数、目标时长或草稿场景估算的值； -- 开场、大纲、总结和来源页默认不占用故事时间轴行； +- 开场与大纲、来源页默认不占用故事时间轴行； - 栏目配置可以明确要求增加其他章节。 当语速、停顿、故事顺序或场景时长改变后，渲染或检查步骤应重新生成时间轴。无法解析最终场景时间线时不得继续沿用旧评论区文本。 @@ -251,9 +254,20 @@ sequenceDiagram 系统应允许审核者通过本地 Web 或受控公网 IP 查看期次 DAG、最终视频、音频、字幕、幻灯、来源、费用和检查结果，并支持媒体拖动与章节跳转。 -临时公网预览应明确协议、鉴权和内容暴露边界。当前明文 HTTP 且无登录的公网 IPv4 入口只能用于有界验收；不应公开原始响应、LLM 请求、详细日志或未批准草稿。 +临时公网预览应满足： -长期外部交付应规划 TLS、访问控制、只读发布包和最小暴露面，但这些能力在规格和授权明确前不得通过临时代理、共享口令或隐藏 URL 假装已经完成。 +- 明确协议、鉴权和内容暴露边界； +- 明文 HTTP 且无登录的公网 IPv4 入口只能用于有界验收； +- 不公开原始响应、LLM 请求、详细日志或未批准草稿。 + +持续外部交付应提供： + +- TLS； +- 访问控制； +- 只读发布包； +- 最小暴露面。 + +这些能力在规格和授权明确前不得通过临时代理、共享口令或隐藏 URL 冒充。 ### 6.6 PUBLISH-L1-REQ-006 版本、纠错与反馈回流 @@ -261,7 +275,7 @@ sequenceDiagram | --- | --- | --- | --- | | PUBLISH-L1-REQ-006 | 版本反馈 | PJ2026-020606 版本反馈 | 全部 L1 | -系统应长期建立发布版本、候选版本、工件哈希、批准决定和平台状态之间的关系，使发布前后纠错可以定位到具体内容和生产作业。 +系统应建立发布版本、候选版本、工件哈希、批准决定和平台状态之间的关系，使发布前后纠错可以定位到具体内容和生产作业。 发生错误时应记录： @@ -281,26 +295,13 @@ sequenceDiagram ## 7. 过程控制 -### 7.1 当前实现状态与引用 +### 7.1 实现引用契约 -- 当前已经实现候选 MP4、封面、字幕、真实故事时间轴、参考来源、费用摘要、技术检查和 Web 预览。 -- 当前没有持久化批准人、批准时间、退回原因、已发布状态、发布版本台账或反馈台账。 -- 当前输出清单不是按内容版本兼容性组合的完整发布包；第 6 章相关条款均为目标需求。 - -- 最终媒体和检查： - - `/root/selfmedia/scripts/src/steps/render.ts`； - - `/root/selfmedia/scripts/src/steps/inspect.ts`。 -- 评论区和引用：`/root/selfmedia/scripts/src/comment-reference.ts`。 -- Web 预览：`/root/selfmedia/scripts/src/server-app.ts`、`web/src/`。 -- 当前期次工件： - - `output/episode.mp4`； - - `output/cover.png`； - - `output/scene-timeline.json`； - - `output/inspection.json`； - - `output/manifest.json`； - - `script/comment-reference.txt`。 -- 后续相关源码修改应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0206 发布运营 draft-2026-07-13-p0`。 +- 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头： + - 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。 +- 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 原入口验收 @@ -315,7 +316,7 @@ sequenceDiagram - 自动检查失败时不得进入人工批准；人工复核失败时不得标记可发布。 - 退回必须指定唯一主责 L1、问题描述和最小重跑范围。 - 重跑后重新生成发布包、场景时间线、评论区文本和检查结果；旧批准不自动继承。 -- 当前未实现平台自动发布和账号权限时，发布动作由人工在平台官方入口完成，系统只交付发布候选和配套文本。 +- 在平台自动发布和账号权限未由独立规格授权时，发布动作必须由授权发布者在平台官方入口完成，系统只交付发布候选和配套文本。 ### 7.4 回写边界 diff --git a/project-management/PJ2026-02/specs/PJ2026-0207-platform-delivery.md b/project-management/PJ2026-02/specs/PJ2026-0207-platform-delivery.md index 7fec089b..672160ff 100644 --- a/project-management/PJ2026-02/specs/PJ2026-0207-platform-delivery.md +++ b/project-management/PJ2026-02/specs/PJ2026-0207-platform-delivery.md @@ -4,9 +4,7 @@ | 版本 | 对应 commit id | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | 2026-07-13 | 建立 Web 内置 Codex、隔离凭据、受控 K8s 部署、自动交付和运行验收目标规格。 | - -当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 +| v0.1 | 2fdadce8 | 2026-07-13 | 定义 Web 内置 Codex、隔离凭据、受控 K8s 部署、自动交付和运行验收的目标能力。 | ## 正文 @@ -19,14 +17,18 @@ | 编号 | PJ2026-0207 | | 短名 | 平台交付 | | 层级 | L1 方向 | -| 状态 | 已生效 | -| 实现状态 | 未实现 | +| 规格状态 | 已生效 | | 实现引用版本 | draft-2026-07-13-p0 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) | | 规格治理索引 | [PJ2026-02 智媒工厂总规格](PJ2026-02-smart-media-factory.md) 第 7 章 | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文定义智媒工厂从本地主机进程演进为可受控交付平台时的稳定目标，不把目标状态写成当前已实现事实。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文边界如下： + +- 只定义受控交付平台的预期终态、目标能力和验收契约； +- 不记录当前运行方式或实现进度。 ## 2. 目的和范围 @@ -39,18 +41,18 @@ - 在容器中提供随镜像交付的源码、CLI 和受限工具； - 通过 YAML-first 配置、GitOps 自动链和公网 IP 原入口持续交付。 -### 2.2 当前状态 +### 2.2 预期终态 -当前 `/root/selfmedia` 已具备本地主机上的 CLI、Web 服务、期次作业和公网 IPv4 临时预览，但尚未实现本规格要求的： +平台交付终态必须具备： -- Web 内置 Codex 终端； -- 包含版本化源码和 CLI 的后端容器运行面； -- PVC 会话持久化、重启自动恢复和 Codex 会话续接； -- YAML-first Secret `sourceRef` 到 `~/.env/TOKEN` 的隔离投影； -- 受控 `~/.codex/*.pika` 源路径到运行时 Codex home 的模型配置与 API key 投影； +- 可从智媒工厂 Web 直接访问的内置 Codex 终端； +- 包含版本化源码、TypeScript CLI 和运行依赖的后端容器； +- 通过 PVC 持久化的 Codex session、supervisor 恢复元数据和重启自动续接； +- YAML-first Secret `sourceRef` 到 `~/.env/TOKEN` 的独立只读投影； +- 受控 `~/.codex/*.pika` 源路径到运行时 Codex home 的独立模型配置与 API key 投影； - 无 ServiceAccount token、无 kubeconfig、无 Kubernetes 或主机权限的终端沙箱； -- GitHub 到 mirror、PaC、Tekton、GitOps 和 Argo 的自动交付链； -- 由公网 IP 原入口执行的部署后运行验收。 +- GitHub、mirror、PaC、Tekton、GitOps 和 Argo 组成的自动交付链； +- 由 owning YAML 选定公网 IPv4 原入口执行的部署后运行验收。 ### 2.3 范围内 @@ -112,7 +114,7 @@ | PJ2026-020705 | 自动交付 | 本规格 6.5 | GitHub、mirror、PaC、Tekton、GitOps 和 Argo 链 | 源码与 owning YAML | 受控部署 | | PJ2026-020706 | 运行验收 | 本规格 6.6 | 公网原入口、版本、终端、恢复、隔离和自动链证据 | 全部平台交付模块 | 发布运营、平台维护者 | -本章图形全部描述目标数据面。当前不存在可与这些目标等价的正式 Kubernetes 运行面，当前差距见第 2.2 和第 7.1 节。 +本章图形全部描述平台交付的预期终态数据面。 ### 5.1 目标数据面架构图 @@ -403,16 +405,13 @@ Kubernetes 工作负载应使用非 root 用户、只读根文件系统或等价 ## 7. 过程控制 -### 7.1 当前实现状态与目标差距 +### 7.1 实现引用契约 -- 当前 `/root/selfmedia` 以主机 Bun 进程运行 CLI 和 Web；这只能作为功能样片和临时公网验收基线。 -- 当前不存在本规格定义的 Kubernetes 应用、Web Codex 终端、会话 PVC、两类隔离凭据投影和 GitOps 自动交付链。 -- 本规格作为目标约束已经生效，但实现状态仍为“未实现”。 -- 所有第 6 章内容都是目标需求，不得用于宣称已经上线。 -- 后续新增或修改的相关源码文件应标记： +- 相关源码文件应标记： - `SPEC: PJ2026-0207 平台交付 draft-2026-07-13-p0`。 - 纯 YAML、生成文件、锁文件和二进制镜像可以不加文件头： - owning YAML、渲染器、容器构建入口和交付流水线必须能追溯到本规格。 +- 实现状态、源码路径、运行面、部署记录和验收证据只进入阶段报告、任务报告、偏离记录或执行 issue。 ### 7.2 实施顺序 diff --git a/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md b/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md index 34e6de67..19466694 100644 --- a/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md +++ b/project-management/templates/iso-iec-ieee-29148-requirements-spec-template.md @@ -13,9 +13,26 @@ 使用原则： -- 业务需求规格用于使命和商业目标，利益相关方需求规格用于用户和运营方诉求，系统需求规格用于跨硬件、软件、人员和流程的系统级要求，软件需求规格用于软件能力要求。运行流程和一次性执行过程不进入 1-6 章需求正文；需要挂阶段 issue、内测、灰度或反馈分流时，放入第 7 章过程控制，稳定概念优先沉淀为术语表。 -- HWLAB 的 L0、L1、L2 规格共用同一骨架，但粒度不同：L0 写使命、边界和全局需求；L1 写内部模块职责和验收边界；L2 写具体课题的交付物、阻塞项和验证计划。 -- 规格正文的 1-6 章只写稳定需求、系统边界、外部输入输出和职责；内部治理、阶段报告、执行流水、长日志、拉取请求过程和一次性运行材料不进入需求章节。第 7 章过程控制只做阶段 issue、反馈分流和敏感信息边界的索引，不承载问卷正文、参与者资料、原始反馈或长证据。 +- 需求规格类型如下： + - 业务需求规格用于使命和商业目标； + - 利益相关方需求规格用于用户和运营方诉求； + - 系统需求规格用于跨硬件、软件、人员和流程的系统级要求； + - 软件需求规格用于软件能力要求。 +- L0、L1、L2 规格共用同一骨架，但粒度不同： + - L0 写使命、边界、预期终态和全局需求； + - L1 写内部模块职责和验收边界； + - L2 写具体课题的目标交付物和验证契约。 +- SPEC 全文只写预期终态： + - 目标能力； + - 稳定边界； + - 目标架构、数据流和接口； + - 原子需求； + - 验收契约和稳定过程控制。 +- SPEC 不写执行态： + - 当前实现状态或能力基线； + - 已完成、未完成、当前阻塞或阶段差距； + - 源码路径、commit、PR、作业、日志、截图、样片或一次性证据。 +- 执行态进入阶段报告、任务报告、偏离记录或 GitHub issue，并从这些载体引用 SPEC。 - 每条原子需求使用独立小节。信息表使用横向表格且只放短元数据，推荐包含编号、短名、主责模块和关联模块；主责模块填写下一层主责单元，L0 写 L1，L1 写 L2，L2 写 L3，不重复当前规格本级；需求定义、职责划分、意图、范围和边界写在正文中，避免表格厚而正文薄。 - 不要为了凑全局需求条目自动添加证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包或结果收集类次要需求；除非用户明确授意，这些内容不进入 OA 规格。 @@ -28,9 +45,9 @@ | 版本 | 对应提交标识 | 更新日期 | 变更说明 | | --- | --- | --- | --- | -| v0.1 | 待提交 | <年-月-日> | 创建需求规格；如来自历史议题，只在这里写迁移来源 <组织>/<仓库>#<编号>。 | +| v0.1 | <提交标识> | <年-月-日> | 创建预期终态需求规格；如来自历史议题，只在这里写迁移来源 <组织>/<仓库>#<编号>。 | -未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本；只有用户明确确认可以定稿时，才更新修改历史。 +修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。 ## 正文 @@ -43,12 +60,18 @@ | 编号 | <项目编号> | | 短名 | <短名> | | 层级 | L0、L1 或 L2 | -| 状态 | 已生效、已废弃或未生效 | +| 规格状态 | 已生效、已废弃或未生效；只表示规格生命周期 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](<相对路径>) | | 上级规格 | <相对路径链接；L0 可留空> | | 规格治理索引 | <相对路径链接> | -本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留稳定使命、范围、术语、系统边界、内部模块或课题分工、原子需求和必要过程控制。编号、层级职责、回写、偏离判定和交叉引用治理由规格治理文档承载。 +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。 + +正文边界如下： + +- 只定义预期终态、稳定使命、范围、术语、系统边界、内部分工、原子需求和验收契约； +- 不记录实现进度、阶段基线或执行证据； +- 编号、层级职责、回写、偏离判定和交叉引用治理由规格治理文档承载。 ## 2. 目的和范围 @@ -101,9 +124,9 @@ ## 7. 过程控制 -本章只索引跨模块阶段验证、内测、灰度或用户反馈分流 issue；不新增 L1，不替代阶段计划，不把问卷、参与者资料、原始反馈、长证据或执行流水写入规格正文。 +本章只定义长期稳定的实现引用、验收、配置、安全、偏离和回写规则。 -| 阶段 issue | 定位 | 关联模块 | 回写口径 | -| --- | --- | --- | --- | -| [#<编号>](https://github.com/<组织>/<仓库>/issues/<编号>) <短名> | <阶段验证或反馈分流定位> | <关联 L1/L2> | <脱敏、分流和回写规则> | +- 当前状态、阶段验证、内测、灰度和用户反馈进入阶段报告或执行 issue； +- 问卷、参与者资料、原始反馈、长证据和执行流水不进入 SPEC； +- 执行载体应引用本 SPEC 编号和实现引用版本。 ```