@infinisys/is-devops 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @infinisys/is-devops
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+GitFox 的 Harness 工程面板与 Agent 工具。
+
+## 面板
+
+侧栏 **DevOps** → `main` 面板：
+
+- 项目选择（`namespace/name`）；
+- 议题：筛选、创建、关闭/重新打开；
+- 合并请求：筛选、创建、合并；
+- 提交：按分支/引用查看；
+- 分支：创建、删除。
+
+所有请求走 Host 代理 `/infinity/devops/api/v1/*`，浏览器不接触 GitFox 令牌。
+
+## Agent 工具
+
+### `infinity_devops`
+
+单工具、多 action：
+
+`status`、`projects`、`issues`、`issue`、`create_issue`、`update_issue`、`issue_notes`、`create_issue_note`、`merge_requests`、`create_merge_request`、`update_merge_request`、`close_merge_request`、`merge_merge_request`、`merge_request_notes`、`create_merge_request_note`、`branches`、`create_branch`、`delete_branch`、`commits`、`commit`。
+
+`project` 使用 `namespace/name`；`iid` 是项目内的议题/合并请求编号。
+
+`update_merge_request` 改正标题/描述（至少给一个），`close_merge_request` 关闭重复或作废的请求；两者都只改同一条记录，不新开记录。关闭后工具会读回记录核对状态：服务器若不支持改状态，会报 `close-not-applied`，而不是把 200 当成已关闭。
+
+`issue_notes` / `merge_request_notes` 读评论区，`create_issue_note` / `create_merge_request_note` 用 `body` 写一条评论。对已有议题/MR 的补充说明应进评论线程，不要新开一个议题来承载。
+
+`create_issue` / `create_merge_request` 自动附加 `bot_name: infinsys-<actor>`。普通 Agent 会话的 actor 是 `infinsys-agent`；`is-fabric-team` 注册 resolver 后，团队角色分别使用 `infinsys-assistant`、`infinsys-dev-backend`、`infinsys-qa` 等。面板代理不会附加 bot，用户在面板中的操作仍记录为真实账号。GitFox 的 `notes` 表没有 bot 字段，评论以令牌账号身份写入，工具不伪造身份。
+
+### `infinity_git`
+
+本地仓库工具，不经 shell、不读取模型提供的仓库路径：
+
+| action | 说明 |
+| --- | --- |
+| `status` | 当前分支与 porcelain 状态 |
+| `diff` | 工作区或索引 diff；`paths`、`stat`、`staged` 可选 |
+| `log` | 最近提交；`limit`、`paths` 可选 |
+| `stage` / `unstage` | 对显式路径操作；拒绝绝对路径、`..`、`.git` 与 pathspec magic。`unstage` 只撤销本席位暂存过的路径，别处的暂存保持原样 |
+| `switch` | 切分支；`branch` 必填，`create: true` 新建（`from` 指定起点，默认当前 HEAD）。工作区有未提交改动时先暂存再恢复，不会被要求手动执行 git |
+| `commit` | 以 `infinsys-<actor>` 作为 author/committer；提交内容 = 该席位暂存的路径，带 `paths` 时只提交这些路径 |
+| `fetch` | 从 GitFox 拉取指定分支到 `refs/remotes/origin/<branch>`；`project`、`branch` 必填 |
+| `rebase` | 在本地对当前分支做变基；`onto` 省略时使用上游，返回 `completed` 或 `conflicted` |
+| `rebase_continue` / `rebase_abort` | 冲突解决并暂存后继续，或放弃变基回到原 HEAD |
+| `push` | 推送到设置页配置的 GitFox；`project` 必填，`branch` 默认当前分支，`force` 使用显式 `force-with-lease` |
+| `delete_branch` | 删除本地分支；`branch` 必填，当前分支返回 `branch-in-use`，`main`/`master` 返回 `protected-branch`，未合并的分支返回 `branch-not-merged`，确认丢弃后用 `force: true` |
+| `prune_worktrees` | 清掉目录已经不存在的 linked worktree 元数据，返回被清掉的条目 |
+
+分支与 worktree 的清理也在工具里：`delete_branch` 只删本地分支（远程分支走 `infinity_devops`），`prune_worktrees` 清掉目录已被删除的 worktree 元数据——试验用的分支和临时 worktree 不必再留给运维手工清理。
+
+暂存按席位记账：`stage` 记下该席位放进去的 blob（`<gitDir>/infinity-git/staged/<actor>.json`），`commit` 从当前 HEAD 加这些 blob 建一个临时索引再提交。因此别的席位暂存的文件、以及暂存之后又被改动的文件，都不会进入这次提交；不带 `paths` 的提交只包含本席位暂存的内容，带 `paths` 的提交只包含这些路径，其余暂存留给下一次。`status` 同时返回 `staged`（本席位下次提交会包含的内容）与 `stagedByOthers`（共享索引里、不会被本席位提交的内容）；没有可提交内容时返回 `nothing-staged`，并说明是哪个席位的暂存挡住了它。
+
+`switch` 在改动无法干净地搬到新分支时返回 `status: "conflicted"` 和冲突文件，改动留在 stash 里，不会丢；清理完文件后用 `stage` 暂存，再手动 drop 该 stash。分支已存在返回 `branch-exists`，起点无法解析返回 `unknown-start-point`，残留的 `index.lock`（超过 30 秒且无进程持有）会被自动清掉。
+
+变基冲突返回 `status: "conflicted"` 和未合并文件列表，不抛错：解决冲突后用 `stage` 暂存，再 `rebase_continue`；也可以 `rebase_abort` 回到原 HEAD。变基本身不做网络访问，`fetch` 负责把目标分支更新到本地。
+
+提交身份来自子进程环境（`GIT_AUTHOR_*` / `GIT_COMMITTER_*`），不修改仓库或全局 `user.*`。推送 token 来自 `infinitySettings`，只通过子进程环境和 URL 作用域 credential helper 生效；token 不进入 argv、remote URL 或工具结果。`main`/`master` 拒绝强推；提交与推送都跳过本地 hook。
+
+GitFox 的 Git HTTP 写入需要 `write_repository`。设置页默认申请的 scope 是 `read_user write_user read_repository write_repository`，新旧 GitFox 的内建 `infinity-system` 客户端都接受这组名字；早期签发的缺写权限 token 需要重新授权一次，否则推送仍会返回 `push-scope-denied`。
+
+## Host 服务
+
+`infinityDevOps` 暴露与工具相同的 GitFox 客户端方法（`listIssues`、`createMergeRequest` 等），以及：
+
+- `botNameFor(actor)`：`infinsys-*` codename；
+- `resolveActor(agent)`：解析当前 Agent 的 actor；无 resolver 时为 `infinsys-agent`；
+- `registerActorResolver(fn)`：供 `is-fabric-team` 把 live 角色、路径白名单和固定项目注入 DevOps / Git 工具。
+
+## 依赖
+
+Host 半依赖 `@infinisys/is-settings` 提供的 `infinitySettings` 服务。请先安装 `is-settings`。