中文说明 | English README
PKR（Project Kernel Runtime，最初称为 Project Knowledge Runtime）是面向 AI 原生软件项目的开放框架与本地项目 Runtime。
PKR 不负责替人或替 Agent 编写代码。它为人、Agent、工具和工作流提供一套 共享的项目规则，以及一个权威的项目状态。Git 仓库保存项目产物，但仓库本身 不是 Runtime 的权威状态。
- Runtime 权威：SQLite Runtime 保存项目状态、权限、策略、事件、证据和 恢复语义；JSON 投影和看板都可以重建，不能反向修改权威状态。
- 受治理的工作流：Steward 准备请求和提案，LPS 负责派发与回收，Agent 在受限 Workspace 中工作；任何参与者都不能把自己的工作报告直接标记为已验收。
- 独立验证：
Done表示声明的 Verification 通过，而不只是进程结束或 Agent 报告成功。 - 边界清晰：PKR 不是模型、云端服务、OS 沙箱、凭据保险库，也不保证受信 主机进程不会损坏本机。
flowchart LR
I[人的意图] --> R[PKR Runtime]
R <--> DB[SQLite 权威状态]
R --> T[受治理的 Goal 和 Task]
T --> W[受限 Workspace]
W --> A[Agent 或工具]
A --> WR[非权威工作报告]
WR --> R
W --> V[独立 Repository Verification]
V --> R
R --> O[验收、阻塞或恢复]
Runtime 记录项目事实，参与者领取有边界的工作并提交实际 Git 证据，独立的 Repository Verification 决定是否具备验收证据。可选的 Supervisor 只负责驱动 受治理的协调动作，不替代 Provider 选择、Owner 审批或独立验证。
当前支持从源码运行。环境要求：Node.js 24.x、Git；运行规范验证还需要 Python 3.11。
npm ci
npm run build
$Pkr = (Resolve-Path .\dist\cli.js).Path
$Target = Join-Path $env:TEMP "pkr-quickstart"
New-Item -ItemType Directory -Force $Target | Out-Null
Set-Location $Target
git init -b main
Set-Content .gitignore ".pkr/"
Set-Content README.md "# PKR quickstart target"
git add .
git -c user.name="PKR Quickstart" -c user.email="pkr@example.invalid" commit -m baseline
node $Pkr init --project $Target --name quickstart `
--outcome "Complete one governed local task"
node $Pkr setup --project $Target --quickstart
node $Pkr doctor --project $Target
node $Pkr run --project $Target --request "Produce one quickstart result"init 为已有 Git 仓库创建本地 SQLite authority；run 记录受治理的
Goal/Task 并返回可领取的工作卡；status 读取并展示持久化的 Runtime 状态。
setup --quickstart 只复制演示用 Verification 文件，不会启用可选 Adapter。
完整的 Agent-native 流程是：
- Agent 注册并领取 Task；
- Agent 直接编辑目标仓库；
lps submit提交工作报告和 Git 前后证据；- 独立执行
verify，由 Runtime 决定是否形成验收证据。
示例命令：
node $Pkr lps claim --project $Target `
--task <task-id> --agent <agent-id> --session-locator "agent-host://current-session"
node $Pkr lps submit --project $Target `
--assignment <assignment-id> --agent <agent-id> --outcome partial
node $Pkr verify --project $Target `
--task <task-id> --assignment <assignment-id>
node $Pkr status --project $Target工作报告是非权威记录，即使协议结果为 verified，也不能替代独立
Verification 或 Runtime acceptance。
项目 intake 缺少必要信息时，会生成只读的 QuestionSheet。问卷答案可以
采用推荐值，但推荐值不等于 Owner approval；涉及受保护决策的跳过或默认推荐
仍然保持阻塞。
node $Pkr project intake --request "Build a playable editor"
node $Pkr project intake --request "Build a playable editor" `
--question-format chat
node $Pkr project intake --request "Build a playable editor" `
--accept-recommended问卷也可以渲染为本地单文件 HTML，供人工查看和导出回答：
node $Pkr visualize questions --project $Target `
--sheet-file intake-question-sheet.json --output reports\intake-questions.html针对 Decision、Task、Verification、Clarification 和 Runtime 事件，可以生成 只读的本地 Wiki-style dashboard：
node $Pkr visualize dashboard --project $Target `
--output reports\decision-dashboard.html --max-events 500两个可视化命令都要求输出路径是目标仓库内的相对 .html 文件，不写入 SQLite，
不创建事件，不改变验收状态，也不访问网络。详细输入、输出和安全边界见
可视化操作指南。
运行完整源码验证：
npm run verify
npm run check:candidatenpm run verify 覆盖规范生成、Schema 校验、TypeScript 构建、Runtime 回归和
敏感数据检查。npm run check:candidate 额外检查 public tree、Markdown 链接、
打包内容、版本和仓库生命周期。
PKR 的权威状态位于目标项目的 .pkr/runtime.sqlite。.pkr/projections/ 下的
JSON 是可检查的派生投影，不能作为 Runtime mutation input。公开源码发布与
npm 发布是两条独立流程；当前包保持 private: true，没有声明 npm 发布或
托管部署能力。
v1.2.0 是当前稳定的 GitHub 源码版本，包含受治理的 Steward intake、
Agent-native LPS、独立 Repository Verification、Runtime acceptance、恢复、
Memory、Workflow、Project Profile、Package 生命周期，以及可选的
Provider-neutral Supervisor。
实验性功能不改变 v1 的权威、审批、验证和恢复边界。完整规范、Schema、发布 检查和安全策略见：
src/：TypeScript Runtime、CLI、Adapter 和测试；specs/：版本化规范与 RFC；schemas/：机器可读的 JSON Schema；conformance/：规范验证器和正反例；docs/：架构决策、操作指南、集成说明和发布策略；examples/：可复现示例；dist/：可重新生成的 TypeScript 输出，不纳入 Git。
源码使用 Apache-2.0 许可证。安全问题请按 SECURITY.md 中的私下报告流程提交。