tta-lab/organon

organon

面向 AI 智能体的结构感知工具，以及 tta-lab 工作区中使用的小型工作流 CLI。

Organon 提供的命令让 logos 智能体能够对代码进行结构化感知，并在 temenos 沙箱中运行。

$ src main.go --tree
├── [aE] func main()               [L1-L15]
├── [bK] func handleRequest()      [L17-L45]
└── [c3] type Config struct        [L47-L55]

$ src main.go -s bK
func handleRequest(w http.ResponseWriter, r http.Request) {
...
}

$ src replace main.go -s bK  playlists/navidrome/mandopop-soft-night.yaml
nd-playlist export-all --output playlists/navidrome
nd-playlist radio diff playlists/navidrome/radios/cliamp.yaml
nd-playlist radio apply --yes playlists/navidrome/radios/cliamp.yaml
nd-playlist radio export > playlists/navidrome/radios/stations.yaml

默认配置位于 ~/.config/nd-playlist/config.toml：

server = "https://music.example"
username = "ooneil"
password = "..."

--server、--username、--password、NAVIDROME_URL、NAVIDROME_USER 和
NAVIDROME_PASS 会覆盖本地配置。如果未配置密码来源且
stdin 是终端，nd-playlist 会提示输入密码。播放列表 YAML
导出包含歌曲 ID，但绝不包含机密信息。

Radio YAML 使用 name、stream_url 和可选的 homepage_url。radio diff
按流 URL 匹配电台，radio apply --yes 仅创建缺失的
电台。将机器拥有的电台文件放在 playlists/navidrome/ 下，该目录
被 Git 忽略。Navidrome 需要管理员账户才能进行此全局更改。

og — 受保护的 forge 操作

og issue 读取 GitHub 和 Forgejo 仓库 issue，而不依赖于
检出分支：

og --project organon issue list --state open --page 1 --per-page 30
og --project organon issue search "credential broker" --state all
og --project organon issue get 42 --json
og --project organon issue comments 42 --page 2

写入仅限 typed-MCP：issue_create、issue_update_title、
issue_replace_body、issue_edit_body 和 issue_comment。创建需要
同时提供标题和正文（正文可以为空）；标题、整个正文、精确批量正文
编辑和评论相互独立。精确编辑在刚获取的正文中
匹配每个旧文本一次，在单次正文更新前拒绝重复/缺失/歧义/重叠或空操作
编辑，并保留所有其他 Markdown 字节。它们
不提供远程 compare-and-swap：同时进行的远程编辑可能产生竞态。
List 默认为 open，search 默认为 all；分页默认为第 1 页 / 30 项，
最多接受 100。评论按最旧优先。提供方的搜索排名和
分词方式不同，且不确定的创建和评论都不会重试。

og 直接在调用 CLI 或 MCP
进程内运行 GitHub PR 和 Git 网络操作。GitHub 身份验证使用由 GitHub
App 铸造的仓库范围安装令牌；不使用 GITHUB_TOKEN、GH_TOKEN 和 github_token_env。Forgejo
继续使用其现有的令牌环境变量。

受控的 og Git 传输仅遵循受支持的用户全局 http.version
值（HTTP/1.1 或 HTTP/2）；所有其他全局和系统 Git 配置
保持隔离。要为存在 HTTP/2 帧
故障的代理路径选择 HTTP/1.1，请运行：

git config --global http.version HTTP/1.1

这是针对 HTTP/2 帧故障的传输偏好，而非修复 TCP
443、TLS 握手、代理节点、路由或 forge 可用性故障。此
例外不会更改任何 API/MCP schema、部署或机密处理行为。

拉取请求合并通过 Impri 进行审批门控。在现有的 ~/.config/ttal/og.toml 中配置可选的
操作员拥有的部分；API 密钥
绝不会被工具请求接受，也不会显示在输出中：

[impri]
base_url = "http://impri.localhost:17480"
api_key = "im_..."
Organon 仅从 og.toml 读取此可选部分；不存在 Impri
环境变量回退或第二个配置文件。

og pr merge --dry-run --pr-id 123 --json 提交一个不可变的 git.merge_pr
操作，其中包含提供方、forge、仓库、PR 编号、head 分支、head
SHA、base 分支、squash 方法和执行模式。结构化结果包括
操作 ID 和 Impri 收件箱 URL。操作员在
Web 收件箱中批准或拒绝该卡片；代理可以使用 --wait --timeout 30s 并重复相同的
project、PR ID 和模式请求来恢复该操作。返回的操作 ID
仅用于审计/Web 识别，不是输入。
Dry-run 批准会记录一次模拟合并，而不更改 forge。真实模式
使用相同的门控，然后重新获取 PR 和 CI，并要求在已批准的 head SHA 处存在一个开放、
可合并的 PR，且 CI 状态为 success 或
not_configured，之后才进行 squash 合并。pr_checks 暴露该机器状态；
对于 not_configured，它还会说明合并策略允许在
没有检查的情况下继续。对于 GitHub，not_configured 具体意味着 Checks API
返回了零个 Check Runs；旧版提交状态集成不在此
门控范围内。待处理、已拒绝、
已过期、超时、格式错误、陈旧和失败的操作不会合并。
提供方/网络/API 可用性故障会使已批准的操作保持可重试；
重复相同的请求，无需新的批准。确定性防护或执行器
故障会将已批准的操作终止为终态 execute_failed；这并不
意味着该 PR 永远无法合并，只是后续尝试需要新的批准。当重复相同的请求时，已拒绝或已过期的操作会自动替换，
即使不可变的 PR 快照未改变。成功的尝试会报告为
executed；真实模式随后记录回执，快进已注册的
单检出默认分支，并仅删除仍然与已批准 SHA 匹配的本地和 origin head 引用。Dry-run 不执行检出切换、拉取
或分支删除。如果回执报告失败，响应会标识
已合并的结果，重复请求会修复回执而不会合并两次。
如果回执后清理失败，响应仍为 executed，并带有
不含密钥的 cleanup_error、retryable=true 和 next_action=retry_same_request。
重复完全相同的 project、PR 和模式请求；forge 合并已经
完成，不得再次运行。完成需要已执行的收据、
成功的默认分支拉取，以及不存在匹配的已批准 head 引用。如果
Impri 批准 GET 或等待轮询暂时不可用，结果就是
本地 unavailable 状态：未进行 forge 调用，且相同的请求
可重试。如果无法记录 execute_failed 回执，结果将保持
已批准且可重试；重复该请求会重新验证并报告
确定性失败，而不是假装 Impri 接受了它。

自动清理支持已注册的正常单检出工作流。它
拒绝脏检出或无关检出，以及任何偏离已批准 SHA 的本地/远程 head ref；worktree 协调不在本版本范围内，正常的 Git worktree 拒绝仍然是错误。og pull 仍可用于其现有的受保护已关闭 PR 工作流，但不是成功真实合并后的第二步。Telegram、webhook、守护进程以及 Impri API 密钥的配置或轮换不在本版本范围内。最终操作员 PoC 使用已配置的已部署 Impri 实例、一个经 Web 批准的 dry-run 卡片，并且不进行真实合并。

只有在两个实现 PR 均已合并、通过检查，并且合并后的二进制文件可供安装后，才创建真实 App。在一个稳定的 GitHub 账户下注册一个 App，并允许其他受管理账户安装它。它不需要 Marketplace 上架、OAuth 流程、回调、webhook 或组织权限。仅授予以下仓库权限：

- Contents：读取和写入
- Pull requests：读取和写入
- Checks：只读
- Actions：只读
- Workflows：读取和写入
- Issues：读取和写入

仅在 tta-lab、GuionAI 和 LamplitIsles 中的选定仓库上安装它。每个安装所有者都必须批准这些权限。不要授予 Administration、Members、Secrets、Deployments 或其他组织访问权限。

在测试写入之前，将每个受管理的默认分支 ruleset 配置为要求 PR 和必需检查、限制更新，并禁止强制推送和删除。将 App 排除在所有绕过列表之外。og 可以访问 main，且其 App token 具有 Contents 写入权限，因此 GitHub rulesets 是硬性合并和默认分支边界。

下载私钥后，将其保存在仓库之外并配置 OG：

install -d -m 700 ~/.config/ttal/og
install -m 600 ~/Downloads/your-app.private-key.pem \
~/.config/ttal/og/github-app.pem
cat  ~/.config/ttal/og.toml
[github_app]
app_id = 123456
key_source = "file"
key_ref = "og/github-app.pem"
allowed_owners = ["tta-lab", "GuionAI", "LamplitIsles"]

[forgejo]
allowed_base_urls = ["http://forgejo.localhost:17480"]
EOF
chmod 600 ~/.config/ttal/og.toml

在替换 pre-direct-execution 安装之前，使用旧的已安装二进制文件停止并移除其用户服务。在 macOS 上：

OLD_OG="$HOME/.local/bin/og"
SERVICE="gui/$(id -u)/io.guion.og.daemon"
"$OLD_OG" daemon stop || true
"$OLD_OG" daemon uninstall || true
launchctl bootout "$SERVICE" 2>/dev/null || true
if launchctl print "$SERVICE" >/dev/null 2>&1; then
echo "old og service is still running; stop it before upgrading" >&2
exit 1
fi
rm -f "$HOME/Library/LaunchAgents/io.guion.og.daemon.plist"

在 Linux 上：

OLD_OG="$HOME/.local/bin/og"
"$OLD_OG" daemon stop || true
"$OLD_OG" daemon uninstall || true
systemctl --user stop og.service 2>/dev/null || true
if systemctl --user is-active --quiet og.service; then
echo "old og service is still running; stop it before upgrading" >&2
exit 1
fi
rm -f "$HOME/.config/systemd/user/og.service"
systemctl --user daemon-reload

直接执行版本没有守护进程生命周期命令；在替换旧二进制文件之前运行此清理。

make install
og auth status --project organon

通过 OG 克隆 URL，使目标、认证和注册保持在同一个边界内：

og clone organon
og clone https://github.com/tta-lab/organon.git
og clone --alias forgejo https://codeberg.org/forgejo/forgejo.git
og clone --reference https://github.com/modelcontextprotocol/go-sdk.git

别名克隆使用已注册的路径和规范远程。URL 项目克隆会派生 ~/code/projects//，其中 owner 和 repository 目录组件为小写，并注册一个别名和远程。引用克隆会派生 ~/code/references///，其中 owner 和 repository 目录组件同样为小写，且保持未注册状态。本地路径与特定于提供方的仓库身份不同，后者的远程拼写会被保留。仅支持 GitHub、已配置的 Forgejo 根以及匿名通用 HTTPS；调用方不能提供目标或凭据。

对于已注册的操作，projects.toml 是仓库身份的 SSOT。在 Git 网络操作之前，og 会立即根据该远程检查有效的 fetch URL，并且对于写入操作，检查每个 push URL，然后再解析令牌。正常的仓库钩子（如 Lefthook）会在不绕过的情况下运行。

已归档的项目条目仍然是有用的上下文。它们可以读取 PR/CI 状态，并使用 og pull 快进已知的默认分支，但不能推送、打标签、创建/修改/评论 PR，或运行 pull 的分支清理路径。

在推广期间保持迁移 PAT 处于活动状态。在每个 owner 中选择一个仓库，运行 og auth status，并要求每个权限都报告为就绪。然后使用一个一次性功能分支验证 og push、og pr view、og pr checks 和 og pr comment。通过类型化的 MCP pr_create/pr_modify 工具验证拉取请求的创建和修改。确认 GitHub 将推送和 PR 活动归属于 App bot。还要验证 SSH 配置的 origin 在磁盘上未发生变化，未安装的托管写入在没有回退的情况下失败，并且第三方公共仓库可以匿名拉取但不能写入。检查命令错误和本地 Git 配置中是否存在凭据材料，但不要打印任何秘密值。此验证通过后，删除下载的密钥副本；GitHub 可以签发替代密钥，因此不需要私钥备份。

只有在所有三个 owner 都通过后，才从 ~/.config/ttal/.env 和 shell 启动文件中移除本地 github_token_env 键和 GitHub PAT 变量。再次运行该命令，重复一次具有代表性的仅 App 推送和 PR 检查，然后撤销迁移 PAT。

安装令牌是自动的、仅内存的、仓库范围的，并约在一小时后过期。App 私钥是长期有效的：它绝不能进入
agent 环境或 Git 子进程。直接调用 git、gh 以及任意 API
调用不在 OG 的凭据边界之内，可能仍会使用个人凭据；在这些路径中，
强制性的 GitHub 规则集保护默认分支。

对于密钥轮换，创建一个替换用的 App 密钥，以 0600 模式安装它，
再次运行 og auth status，验证所有所有者，然后撤销并
删除旧密钥。在撤销 PAT 之前，回滚意味着重新安装
之前的 og 二进制文件，并使用现有的迁移 PAT 停止并卸载旧服务。
撤销之后，紧急回滚需要一个新的、范围狭窄的临时 PAT；切勿
重新激活或复用已暴露的迁移 PAT。

MCP 服务器

og 和 skill 提供类型化的 stdio MCP 服务器。og mcp 结合了本地
项目发现、只读源代码搜索/检查以及受保护的 forge
工作流。项目发现和源代码检查无需 forge 凭据
或网络可用性即可工作：

{
"mcpServers": {
"organon-og": { "command": "og", "args": ["mcp"] },
"organon-skill": { "command": "skill", "args": ["mcp"] }
}
}

使用 project_get 或 project_list 来发现确切的五字段项目
记录：别名、名称、路径、规范远程仓库和归档状态。活动别名
是单层名称，不能包含点号。项目注册表更新在
下一次 MCP 调用时可见。面向仓库的 og 工具接受项目引用，但不接受文件系统
路径、工作目录、MCP 根目录、文件 URI 或凭据。源代码工具也
接受与已注册检出完全相等的绝对路径；其文件路径
必须保持在该检出内。clone 则接受 URL。og MCP 进程在其
首次 forge 调用时初始化配置，然后在其生命周期内保留 Git、注册、策略、凭据或该
初始化错误。

skill mcp 暴露 skill_list、skill_find 和 skill_get。在没有项目
参数时，它仅搜索全局技能目录。使用确切的已注册
别名时，项目本地技能优先于全局技能。结果使用稳定的
源标签，例如 project:.agents，而不是发现根路径。
skill_find 接受一个自然语言 query 和一个可选的 limit，然后
对技能名称、描述和类别中的词元匹配进行排名。
CLI skill find 命令使用相同的查询验证、默认值、限制
和排名行为。
单个大于 1 MiB 的 SKILL.md 文件在解析前会被拒绝。

og mcp 暴露类型化的项目发现、只读的 source_search、
source_symbols、source_read 和 repo_diff，以及 auth、clone、push、pull、PR
create/find、PR get/modify/comment/checks/log/failures 和经批准门控的
pr_merge。source_search(project, pattern, limit?) 接受一个 ripgrep
正则表达式模式作为单个参数；Organon 控制所有 rg 标志
和已注册检出根目录。repo_diff(project, path?) 返回已跟踪的
从本地默认分支合并基点到工作树的统一 diff，
以及文件摘要和未跟踪路径。它不会进行抓取，并且会将
补丁限制在标准工具输出上限内。Create 和 modify 被限定为仅限类型化 MCP，因为它们的
用户可控的 title/body 字段可能包含多行自由文本；通过 shell CLI 参数
暴露这些正文会重新引入引号和
转义歧义。pr_merge 仍可通过类型化 MCP 和
og pr merge 两种方式使用，因为其输入是结构化的短标量标志；agent
应默认使用 MCP，并且两个适配器调用相同的 Impri 审批门控
领域操作。

合并调用方消费结构化结果字段 status、retryable、
next_action、completion、detail、action_id、inbox_url、
receipt_error、cleanup_error 和
snapshot。action_id 仅用于审计/Web 识别。展示收件箱
并等待待处理操作；retry_same_request 表示重复完全相同的
项目、PR ID 和模式请求；将已执行且没有回执或清理
错误视为完成。在拒绝或过期后重复同一请求会创建一个
替代审批，而最终执行失败仅结束该
审批操作，之后的合并尝试需要新的审批。本地
unavailable 状态表示审批状态未知，未进行任何 forge 调用，
并且同一请求可重试。已执行结果带有 receipt_error 时使用
repair_receipt，并且仅用于修复 Impri 回执而重复，绝不用于
再次合并。已执行结果带有 cleanup_error 时使用
retry_same_request；它报告 forge 合并已完成，清理
必须在不进行另一次 forge 调用的情况下完成。完成意味着已执行且既无
回执错误也无清理错误。
MCP 当前
分支工作流使用已注册检出项的当前分支。强制推送使用
force-with-lease，并且在默认分支上会被拒绝。Pull 保留 CLI 的
受保护已关闭 PR 分支清理。正数 PR ID 选择无分支的远程
操作；当省略 ID 时，pr_get、modify、comment、checks、log 和 failures 使用当前
分支。Tag 仍仅限 CLI。更改 og.toml 后启动新的 og 进程。运行
mcp --help 以查看每个服务器的工具列表和配置详情。

Pi 扩展

Pi 唯一的原生 Organon 包是 @tta-lab/pi-src，它用符号感知操作和精确的多重编辑
批次替换 Pi 内置的 read 和 edit。Pi 通过其现有的
og mcp 集成访问项目发现和 forge 工作流；Organon 不为这些工具提供 Pi 桥接。有关 pi-src 安装、平台、开发和
发布指南，请参阅
pi/README.md。

为什么

通过 shell 命令工作的 AI agent（如 logos）无法进行多行文件编辑。每个现有的编辑工具都使用结构化 JSON 参数——{"path":"file","edits":[{"oldText":"...","newText":"..."}]}——这需要工具调用协议，而不是 shell。
Organon 通过用符号定位取代文本匹配来解决这个问题。LLM 不需要复现旧代码——它请求符号树，选择一个 ID，然后通过单个 heredoc 传入新代码。一个 stdin 参数，而不是两个 JSON 字段。

安装

Homebrew

brew install tta-lab/ttal/organon

从源码

CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/src@latest
CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/skill@latest
CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/og@latest
CGO_ENABLED=0 go install github.com/tta-lab/organon/cmd/nd-playlist@latest

从发布版本

从 GitHub Releases 下载二进制文件。

如何契合

temenos (sandbox)
├── organon tools (pre-installed)
│   ├── src    ← structure-aware file read/edit
│   ├── skill  ← skill discovery
│   └── og     ← project discovery plus guarded Git and forge operations
├── standard tools (cat, ls, grep)
└── user code

logos (agent loop)
├── LLM writes: $ src main.go --tree
├── temenos executes in sandbox
├── output fed back to LLM
└── LLM writes: $ src replace main.go -s bK <<'EOF' ... EOF

设计

- 小型核心，薄适配器 —— CLI 和 MCP 命令共享类型化的内部
服务，而不是重复业务规则。大多数命令解析、执行，
然后退出；og 在调用进程中组合其凭据和策略。
- 内容使用 Stdin —— 新代码通过 heredoc 传入。一个多行参数，而不是两个。
- 2 字符 ID —— 用于符号/区块的 base62 标识符，与 flicknote 相同的系统。
- Tree-sitter —— 语法级 AST 解析。无需 LSP 服务器。
- 语言检测 —— 从文件扩展名进行。无需 --language 标志。

名称

亚里士多德的 Organon*（ὄργανον，“工具”）是他关于逻辑的文集——使推理成为可能的工具包。这些工具是 logos 用来推理代码的工具。

| 项目 | 角色 |
|---------|------|
| temenos | 边界——沙箱隔离 |
| logos | 理性——智能体循环 |
| organon | 工具——感知与行动 |

许可证

Apache-2.0