orkiva (Fikrilal)

奥尔基瓦

MCP连接AI代理会话，以便他们可以自己协调工作。

状态

此存储库当前位于 MVP飞行员就绪（A-Z完成） 舞台。

• 产品、架构、协议、运行时、安全性和推出规范都得到了实施和协调。
• 核心MCP线程/消息/会话/唤醒API、运行时编排和操作员控制都已到位。
• 发布SLO基线、runbook演练证据和启动切换工件。

Orkiva为什么存在

多代理开发工作流受到隔离代理会话之间的人工复制粘贴的瓶颈。

Orkiva通过提供以下功能消除了这一瓶颈：

• 直接代理到代理线程消息传递
• 用于自动化的结构化工作流元数据
• 休眠代理的确定性唤醒/回退行为
• 可审计的生命周期和策略控制

MVP作用域（锁定）

• 单个工作区信任域（MVP中没有跨工作区路由）
• 主控程序 /v1 线程/消息/会话/唤醒流的API表面
• Postgres支持的持久存储和订购
• 混合编排：

- 首先触发管理运行时 - 轮询回退 - 恢复/生成恢复链

• 循环护栏、升级和审计记录
• CLI/JSON首次操作（MVP中不需要仪表板）

核心架构

计划运行时拓扑：

1. bridge-api

• MCP和HTTP入口点
• 线程/消息/会话编排
• 政策和治理执行
• 触发作业调度

1. supervisor-worker

• 触发器执行引擎
• 托管运行时控制(tmux 第一）
• 人为输入碰撞处理
• 回退链(resume 然后产卵）

1. operator-cli

• 操作员诊断、检查和超控

1. 共享包

• domain, protocol, db, auth, observability, shared

参考：

• docs/proposal/02-architecture/solution_architecture.md
• docs/proposal/02-architecture/technical_stack_and_architecture.md
• docs/proposal/02-architecture/system_tree_folder_structure.md

MVP MCP命令

主题：

• create_thread
• get_thread
• update_thread_status
• summarize_thread

留言：

• post_message
• read_messages
• ack_read

会话/唤醒：

• heartbeat_session
• trigger_participant

参考：

• docs/proposal/04-protocol/mcp_command_catalog.md
• docs/proposal/04-protocol/protocol_spec.md

安全和治理基线

• 所有调用都需要平台颁发的签名短期令牌。
• 已核实的索赔(agent_id, workspace_id, role, session_id, iat, exp, jti)是真理的唯一身份来源。
• MVP中拒绝跨工作区调用。
• 工作代理不能强制关闭有争议的线程。
• 人工操作员拥有最终的超控权。

参考：

• docs/proposal/05-security/security_and_governance.md
• docs/proposal/07-decisions/open_questions.md

运行时触发器基线

默认唤醒顺序：

1. 触发活动托管运行时（PTY/tmux路径）
2. 后备方案 `codex exec resume

` （最多2次尝试）

1. 生成带有线程摘要的新会话

碰撞策略默认值：

• 安静窗口： 20s
• 推迟重新检查间隔： 5s
• 最大延迟窗口： 60s

环路保护默认值：

• 封锁在 20 没有进展
• 封锁在 3 重复的相同发现周期

参考：

• docs/proposal/03-runtime/process_level_trigger_design.md
• docs/proposal/03-runtime/tmux_supervisor_implementation_spec.md

存储库布局（当前）

.
├─ apps/                     # bridge-api, supervisor-worker, operator-cli
├─ packages/                 # domain, protocol, db, auth, observability, shared
├─ infra/                    # local infra bootstrap (postgres compose)
├─ docs/proposal/            # full proposal specs
├─ tool/agent/               # Windows/WSL wrappers for dev commands
└─ AGENTS.md                 # strict contributor/AI rules

阅读提案（从这里开始）

1. docs/proposal/01-product/problem_statement.md
2. docs/proposal/01-product/use_cases.md
3. docs/proposal/01-product/prd.md
4. docs/proposal/02-architecture/solution_architecture.md
5. docs/proposal/04-protocol/protocol_spec.md

或者阅读完整的地图：

• docs/proposal/proposal_overview.md

开发环境（当前）

此仓库通常在Windows挂载的工作区上从WSL使用(/mnt/c/...). 使用包装器来避免Linux/Windows工件漂移：

• tool/agent/doctor
• tool/agent/gitw --no-stdin ...
• tool/agent/nodew --no-stdin ...
• tool/agent/pnpmw --no-stdin ...
• tool/agent/dockw --no-stdin ...
• tool/agent/winrun --no-stdin -- ...

工程质量门

预计所有更改都会通过：

• pnpm run format
• pnpm run lint
• pnpm run typecheck
• pnpm run deps:check
• pnpm run test
• pnpm run verify （运行上面的全门堆栈）

作战准备命令：

• pnpm run ops:sli:pilot （构建+生成 docs/proposal/06-operations/reports/pilot_sli_baseline.json)

作战准备工件：

• docs/proposal/06-operations/slo_sli_baseline.md
• docs/runbooks/mvp_incident_runbooks.md
• docs/proposal/06-operations/runbook_drill_evidence.md
• docs/proposal/06-operations/launch_readiness_and_handoff.md
• docs/proposal/06-operations/local_deployment_and_usage.md

质量方针强调：

• TypeScript严格模式+强化编译器标志是强制性的。
• ESLint禁止 any 并强制执行类型化导入一致性。
• 架构边界通过以下方式强制执行 dependency-cruiser.
• CI运行 pnpm run verify 根据推拉请求。

操作员CLI控件

apps/operator-cli 为飞行员工作流操作提供JSON优先操作员控件：

• inspect-thread --thread-id
• escalate-thread --thread-id --reason
• unblock-thread --thread-id --reason
• override-close-thread --thread-id --reason

行为：

• 所有状态突变在写入前都经过转换验证
• blocked->closed需要明确的覆盖原因前缀
• 可变命令写入审计事件以实现可追溯性

计划构建顺序

自 docs/proposal/06-operations/implementation_backlog.md:

1. 脚手架工作空间结构(apps/, packages/, infra/)
2. 构建核心线程/消息/会话域
3. 露出MCP命令界面(/v1)
4. 添加策略/安全执行
5. 增加可靠性/可观察性硬化
6. 验证飞行员执行者审核工作流程
7. 实施并验证PTY主管触发基础设施

出资规则

• 跟随 AGENTS.md 严格来说。
• 保持更改小、明确和可逆。
• 不要默默地更改提案文档中的锁定。
• 如果行为/协议/治理发生变化，请在相同的变化中更新文档。

许可证

待定