Skip to content

token-forge-page.md

Latest commit

 

History

History
170 lines (131 loc) · 10.9 KB

token-forge-page.md

File metadata and controls

170 lines (131 loc) · 10.9 KB
Raw

Token Forge 正式页面、仓库证据与事件合同

P1-006 把 P1-002 的确定性模板和 P1-005 的本地导出接到 /token-forge/；P1-007 在同一页面加入可选的 P1-003 公开 GitHub 仓库摘要；P1-008 再加入显式选择的服务端 AI 增强；P1-009 为最终 计划增加确定性质量评分和依赖安全排序；P1-010 允许用户在当前标签页内编辑、锁定和 重新规划结果；P1-011 从最终计划生成 Provider-neutral Coding Agent 执行包；P1-012 增加三档一键模板样例、渐进引导、错误恢复与移动端结果导航。

用户路径

  1. 静态 HTML 说明无需登录、仓库可选且只读公开数据、AI 仅显式触发、不保存输入；
  2. 用户可一键运行 6K 完全本地、24K 公开仓库或 40K 完全本地样例；也可输入 Token 预算、到期天数、可投入工时、技术栈、可公开目标和可选仓库 URL；
  3. 浏览器先做数值约束、允许字段映射、PII 脱敏和 Secret 拒绝；
  4. “仅生成模板”直接生成 mode: "template" 的确定性计划和本地导出；
  5. 仓库 URL 留空时不发网络请求；URL 有效时，P1-003 只向固定 GitHub API Origin 读取受限 的公开元数据、目录树和文本样本；
  6. 成功时页面只保留固定技术标签、覆盖计数和代码生成的未知项；路径与文件正文不会进入页面 结果；
  7. “AI 增强生成”只发送 allowlist 目标、约束与脱敏后的最多 4 个无路径公开片段；浏览器 不含 API Key、模型或系统指令；
  8. AI 候选计划重新通过 Schema、依赖、Token、工时、脱敏、生产写入和仓库回显校验；成功 时采用增强计划；
  9. 六项确定性规则为任务评分，并在依赖已经满足的可执行集合中按分数排序；
  10. 用户可本地修改任务、锁定、删除、手动移动或调整预算；每次应用重新验证合同、质量与 三种导出；
  11. 用户显式选择质量排序时重新运行依赖安全排序；存在锁定任务时不覆盖用户确认的位置；
  12. 最终计划一一映射为依赖安全的 Coding Agent 阶段，附上下文、验收、交接和失败恢复；
  13. 无效 URL、私有/不存在仓库、限流、超时、网络失败或无效响应只让对应证据降级，已经验证 的模板计划和导出继续可用；
  14. 用户复制或下载产物，是否提交给 Coding Agent 或 GitHub 由用户决定。

P1-012 的详细样例、三步状态、错误恢复与锚点合同见 首次使用与移动端闭环。

修改任一表单字段后旧结果立即失效。异步仓库请求带页面运行版本：过期请求即使稍后返回，也 不能覆盖新表单的状态。

表单边界

字段 页面约束
Token 预算 2,000–60,000 的整数
到期时间 1–30 天的整数
可投入时间 1–80 小时，步长 0.5 小时
技术栈 1–8 项，逗号、中文逗号、分号或换行分隔
公开仓库 可选；最多 200 字符，只接受规范的 https://github.com/{owner}/{repo}
目标 10–500 字符

目标和技术栈是不可信自由文本。邮箱、IP 等 PII 在进入计划前脱敏；Token、Cookie 和 Authorization 等 Secret 直接拒绝，错误消息不回显原值。

仓库 URL 先由固定解析器规范化，不经过自由文本域名脱敏。地址无效时，页面会删除无效地址后 生成模板结果，并显示稳定的仓库降级原因；不会把原地址写入错误消息。

仓库状态与安全投影

页面只公开三种仓库状态：

状态 页面行为
not-requested 不请求网络，显示“未提供 · 未读取”
summarized 显示目录项、读取、忽略、截断和未知计数，以及固定技术标签
fallback 显示稳定失败类别，保留模板计划和三种导出

“忽略”由疑似秘密路径/内容、二进制或生成文件、过大文件、读取失败和采样上限计数相加。 “截断”是目录树截断标记的 0 或 1。页面还显示各跳过类别，避免把受限样本误认为完整 仓库审计。

原始摘要只在当前标签页内短暂存在。页面投影明确丢弃：

  • 仓库 owner、name、默认分支和原始 URL；
  • 文件路径、大小明细和 untrusted_text 正文；
  • 适配器原始未知项与原始错误消息。

技术标签只允许 TypeScript、Astro、Node.js、Python、Go、JVM、Rust 和 Docker 固定枚举； 未知项由覆盖计数重新生成。仓库内容不会进入模板任务、Analytics、站点 URL、日志或存储。 只有用户选择 AI 增强时，脱敏、截断且移除路径的公开片段才会短暂进入模型请求；原始摘要 仍不会进入 Markdown、Issue 草稿、Agent 执行包或策略快照。

网络边界继续由 P1-003 适配器 强制：固定 https://api.github.com、无 Authorization、禁止重定向、最多 8 个文件、单文件 32 KiB、总计 128 KiB、目录树 2,000 项、单次请求超时 5 秒，且只对 5xx 重试一次。

最小事件合同

事件使用 token-forge-event-v1.schema.json， 只允许以下五个字段：

  • schema_version：固定 1.0；
  • event_name：lab_open、run_success、run_failure、export、blog_click 或 github_click；
  • lab_id：固定 token-forge；
  • lab_version：固定 1.0；
  • device_category：mobile、tablet、desktop 或 unknown。

未知字段在事件边界丢弃。表单值、目标、仓库 URL、仓库覆盖、计划、导出正文、错误正文、 输入长度和高精度设备数据都不属于事件。仓库读取降级但模板成功时记为 run_success，因为 用户仍取得完整本地产物；只有表单或本地合同失败才是 run_failure。

P4-003 默认接收器只向同源 /api/token-forge/events 发送通过合同的事件，不带 Cookie 和 referrer，也不重试。Worker 再次执行允许字段映射与 Schema，随后只保存 31 天的 “UTC 日期 × 事件 × 粗设备类别”聚合计数；不保存原始事件、单次时间戳、访客/会话 ID、 来源、User-Agent 或网络标识。同步、异步、网络或存储失败都不得中断生成、导出和导航。

持久化合同与限制见 Analytics 规范 和 ADR-0007。当前没有公共统计读取 API； 事件次数不等于唯一用户，P4-008 必须按方向性漏斗解释。

AI 状态与隐私

页面只公开三种 AI 状态：

状态 页面行为
not-requested 完全使用本地模板，不向模型发送目标或摘要
ai-assisted 显示最终验证计划、总 usage 与尝试次数
template-fallback 丢弃候选输出，显示模板和稳定降级状态

服务端固定主模型、顺序回退模型、端点、指令、每模型 22,000 输入、2,000 输出、共享 45 秒和 1 次 Gateway 尝试。API Key、匿名用户键、原始 IP、上游错误正文和无效模型正文 不会返回页面。服务端与浏览器都不记录目标、仓库片段或计划正文。

规则质量与排序

页面把 P1-009 质量结果 明确显示为“确定性规则质量”，不与 AI 解释混合。计划卡显示整体分数与需人工修改数量；每项任务显示分数、状态，并可展开六项 规则的编号、得分和稳定解释。

任务顺序只在依赖已经满足的候选中按分数下降排列，同分保留输入顺序。排序原因使用 QF-O01 至 QF-O03，仓库证据限制使用 QF-E01 至 QF-E03。页面与导出共用重排后 计划；质量结果本身不进入 URL、Analytics、服务日志或持久化。

本地编辑状态

P1-010 编辑器 只在生成成功后创建页面内部 TokenForgeEditorSession 1.0。任务 ID 与依赖只读；其他任务字段、预算、锁定、删除和 相邻顺序可由用户控制。手动顺序使用 QF-O04，并在每次应用时重新检查依赖先行。质量分 只提供提示，不会在用户未点击“按质量重新排序”时覆盖手动顺序。

编辑状态、修订次数与锁定列表不持久化，也不进入最小事件合同。修改顶部生成表单、刷新或 关闭标签页会清除状态；“恢复生成结果”可以在当前标签页内回到本次生成的基线。所有编辑 继续经过 PII 脱敏和 Secret 拒绝，本地操作不调用 AI。

Coding Agent 执行包

P1-011 执行包 与完整计划、Issue 草稿共用最终验证顺序。 页面显示第三张导出卡，可复制或下载 token-forge-agent-package.md。每个阶段保留任务 预算、依赖、Prompt、范围和验收，并增加固定的允许/禁止上下文、仓库原生命令发现协议、 阶段交接模板和失败恢复。

执行包不会把受限仓库摘要变成文件路径或命令事实，也不包含仓库 URL、原始正文、模型配置 或隐藏服务端指令。它只在浏览器内确定性生成，不调用 AI、GitHub 或外部执行工具；用户 决定是否把 Markdown 交给实际 Coding Agent。

静态与可访问性

  • 标题、主标题、隐私合同和表单由 Astro 预渲染，禁用 JavaScript 时仍可索引和理解；
  • Preact 工作台使用 client:visible，不抢占首屏加载；
  • 控件使用原生 label、input、select、textarea、details 和 button，提示通过 aria-describedby 关联；
  • 加载时表单使用 aria-busy，提交按钮禁用并显示文字状态；
  • 成功、提示、降级和错误同时使用文字、符号与 ARIA 状态，不仅依赖颜色；
  • 触控目标不小于 44px，字段、任务、覆盖计数和导出卡在 800px/600px 断点重排到单列；
  • 三档样例在 800px 以下重排为单列，三步引导与结果导航在 600px 以下使用窄屏网格；
  • 生成成功后只聚焦结果标题一次；本地编辑不抢焦点，失败时可回到首字段或运行 6K 样例；
  • reduced-motion、forced-colors 和键盘焦点沿用站点基线。

构建后的首页与正式页面由静态合同脚本共同验收。