前几天把 AI DevOps / QA Copilot 的终端客户端发上了 PyPI：
aidevops，
pip install aidevops 就能装。源码在
GitHub，MIT 协议，
项目完全开源。
这篇文章把它讲透：它解决什么问题、数据是怎么流动的、风险分是怎么算出来的、AI 在里面扮演什么角色（以及为什么它被关在笼子里）、每个命令怎么用，还有哪些是我刻意不做的。
一、它在解决什么问题：研发数据的孤岛
一个团队日常会产生大量研发数据：需求单在 Jira 里、提交在 GitHub 里、测试结果在 CI 里、Bug 单在缺陷系统里、发布记录在发布流水线里。这些数据都存在，但
散落在不同系统里，彼此不认识。
于是每个开发者每天都在人肉做同一件事：这次改动动了哪些模块？这些模块历史上出过什么 Bug？相关的测试有没有覆盖？这个版本发出去，风险集中在哪？——答案全在系统里，但要把它们拼起来，得开五个标签页、翻三份导出、再凭记忆对一遍。
aidevops 背后的平台做的就是这件事：
把「需求 → 代码 → 测试 → Bug → 发布」这条链路上的数据关联起来，然后回答四类具体问题：
- 一次提交风险在哪里（哪个模块、哪个信号在报警、为什么）；
- 该回归测试什么（关联的历史 Bug、测试候选清单）;
- 线上问题最可能从哪来（关联链回溯到需求和发布）；
- AI 看完数据后建议什么（生成测试、标记可疑点、给出调查方向）。
aidevops 这个终端客户端，就是把上述能力装进命令行——因为在终端里工作的开发者，不应该为了看一次风险分析切到浏览器。
二、总体架构：客户端薄，服务端厚
一句话：
aidevops 是终端客户端（CLI + 全屏 TUI），不是服务端。 它本身不含任何业务逻辑，所有能力都通过 HTTP 调用后端（Django + PostgreSQL + Redis，向量检索用 pgvector）。
这个边界划得非常刻意，原因有三：
- 数据与逻辑集中在服务端：关联引擎、风险模型、AI Agent 都是重计算 + 需要完整数据的组件。同步进来的提交历史、测试台账、Bug 单动辄几十万条，放客户端会退化成玩具；
- 凭据安全：Git 凭据、模型 API Key 存在服务端并 Fernet 加密落库，客户端只持有自己的访问令牌（存本地配置目录，权限 0600）；
- 多端复用：CLI、TUI、未来的 Web 前端，全部消费同一套 REST API（
/api/v1），不存在逻辑漂移。
所以如果你只装了
aidevops 而没有可用的后端，
login 第一步就会连不上——这不是 bug，是架构。本地起后端两条路：
cp .env.example .env 后
docker compose up -d --build（Swagger 在
/api/docs/），或者
make install && make migrate && make run 加
make worker /
make beat 起 Celery。
客户端技术栈：
Typer（CLI 框架）、
Textual（全屏 TUI）、
Rich（表格与美化输出）、
httpx（HTTP 客户端）。纯 Python 依赖，没有需要编译的扩展，Python ≥ 3.11。
三、数据是怎么进来的：双游标同步与幂等摄取
数据进不来，后面全是空态。摄取层是整个系统最「脏活累活」的部分，三条通道：
GitHub REST 同步：增量游标 + 历史回填游标分开维护——新提交走增量，首次接入的仓库全量回填。限流退避重试（GitHub 的 rate limit 是现实约束，不是异常）。
Webhook 实时摄取：push、CI 结果、issue 变更等事件实时进来。两道安全门：
HMAC-SHA256 验签（确认请求真来自 GitHub）+
delivery_id 幂等（GitHub 会重投事件，同一条 delivery 处理两次不能产生两条记录）。
Celery beat 定时兜底：Webhook 会丢（网络抖动、服务重启），beat 定时任务周期性对账，保证最终一致。
模块归属、测试关联这些「理解性」工作在摄取完成后异步进行。这套设计的取舍很明确：
摄取层宁可慢，不可丢、不可重——因为后面所有关联和风险计算都建立在「数据是可信的」这个前提上。
四、模块归属：把提交钉到模块上
关联的第一步是回答「这次提交动了哪些模块」。听起来简单，实际是个解析问题：同一个仓库里，
src/auth/ 显然属于 auth 模块，但
utils/date.py 属于谁？改了
tests/ 的提交算不算动了业务模块？
aidevops 的解法是
三级归属策略，按优先级落：
- 覆盖规则（最高优先）：仓库维护者显式配置的路径 → 模块映射，一票定音；
- 源根推断：没有覆盖规则时，按语言惯例和仓库结构推断（比如
src/、lib/ 下的顶层目录）；
- 兜底策略：以上都不适用的文件，落到明确的兜底归属，不悬空。
关键在最后半句：
每一种归属都带可引用的理由。「这个文件属于 auth 模块，因为它命中了覆盖规则
src/auth/**」——归属不是猜的，是可以点开看的。下游的风险计算、回归候选推荐全部建立在这层可追溯的归属之上。
五、explain：一条提交的完整关联链
aidevops explain <sha> 是招牌命令。给一个提交 SHA，它返回这条提交在研发链路上的完整关联：
- 关联需求：这个改动是为了哪个需求（或关联到哪个需求簇）；
- 模块影响：改动了哪些模块，每个模块的中心度如何；
- 回归候选：历史上和这些模块纠缠最多的测试与 Bug，哪些应该跑；
- 历史 Bug：同区域过去出过什么问题，模式是什么；
- 所在发布：这条提交进了哪个发布，发布窗口什么时候；
- 数据缺口：上面哪些环节没有数据。
最后一点值得单独强调：
data_gaps 显式区分「没有发现问题」和「我们没有数据」。工具最大的失信方式就是把无知包装成结论——比如一个从没接过测试结果的仓库，「回归候选为空」必须被解释成「我们不知道」，而不是「一切安全」。这是整个产品的诚信底线，explain 把它做成了输出的一等公民。
六、风险引擎：10 个信号，逐条可解释
aidevops risk <sha>（以及模块维度的
aidevops module-risk <id>）给出归一化的风险分数。它刻意做成
可解释的：10 个信号各自贡献多少，逐条列出，贡献之和精确等于分数。
三个工程决策值得展开：
- 权重是配置而非代码。10 个信号的权重存在服务端，可以在 Django admin 里调，不需要改代码重新部署；
- 三级继承：系统默认 → 组织覆盖 → 项目覆盖。一个对延迟敏感的团队可以把「临近发布」权重调高，一个测试基建薄弱的团队可以突出「覆盖缺口」；
- 贡献之和等于分数。这不是装饰——它让「我觉得这个分数不对」变成可讨论的工程问题：找到贡献最大的信号，去查它的输入。黑盒分数永远做不到这一点。
七、AI 分析：五个 Agent、证据校验、全链路追踪
AI 层回答「看完这些数据，能不能自动做点什么」。它的结构比「接个 LLM」复杂得多：
Provider 可插拔。模型凭据按组织管理（
aidevops providers /
provider-add /
provider-verify），走 OpenAI 兼容协议，内置 DeepSeek、Qwen、Ollama 预设，凭据 Fernet 加密落库——模型 Key 和 Git PAT 一样，不属于客户端。
五个内置 Agent，各自有明确的输入输出契约：
发起用
aidevops analyse -a test-generation --wait，历史用
analyses /
job 查。
aidevops trace <id> 是排障神器：一次分析背后的模型调用、工具调用、各自耗时，全部可查——Agent 不是黑盒。
aidevops findings / finding <id> / triage <id> <status> 是 AI 发现的工作台：每条发现都带
证据引用——AI 说的话必须能解析回真实数据（某个提交、某条 Bug、某段测试），引用对不上就不会出现。
triage 把发现的处置状态（待处理 / 已确认 / 误报）做成显式流转，处置过程本身就是团队的知识沉淀。
aidevops tui 是全屏交互式仪表盘（Textual 实现），提交列表、发现流、建议队列都在里面，不想记命令就开它。
证据校验是 AI 层的硬约束：AI 的每条引用（某个提交、某条 Bug、某个测试）必须能解析回真实数据，解析不上就不会出现在结论里。这从机制上掐掉了「模型幻觉出一条不存在的 Bug」这类事故。
工具面收口：模型只能调用 13 个
只读工具，全部强制按项目作用域过滤，任何写操作都不在模型的工具列表里。AI 看得到数据，但碰不到状态——这是下一节确认流的前提。
八、确认流与审计：AI 只提议，人说了算
AI 的产出永远是「建议对象」（proposal）：生成的一批测试、一个调查结论、一个处理建议。它们不会自己生效：
aidevops proposals # 看待确认的建议
aidevops approve <id> # 确认 → 代码固定的 Executor 执行
aidevops reject <id> # 拒绝 → 丢弃
三条硬规则：
- 只有
approve 会真正执行。执行逻辑不在模型手里，在代码写死的 Executor 里——模型只能「提」，不能「做」；
- 未确认 = 零写入。没有隐式的自动采纳，没有「默认执行、异议再撤销」；
- 全程写
AuditLog。谁在什么时候 approve 了什么、Executor 做了什么，aidevops audit 一条条可查。
在 QA 这个场景里，这个取舍很明确：
AI 直接改状态的信任账还没到能赊的程度。测试是质量防线，防线上不能放一个会自己动手的黑盒。
多租户安全是同一思路的延伸：
租户 id 只从 URL 取（不从请求体猜），非成员访问返回 404（不泄露存在性），角色不足返回 403，所有查询强制走
scoped_queryset 唯一入口——没有「忘了加过滤」这种事故的容身之处。
九、安装与五分钟上手
pipx install aidevops # 推荐：独立虚拟环境，命令直接进 PATH
# 或者
pip install aidevops
登录走
GitHub 设备码（device flow），浏览器输个码就行，不在终端贴密码；远程服务器 / 容器用
login --no-browser。
aidevops login # GitHub 设备码登录
aidevops org-add "My Team" # 首次使用：建组织（创建者即 admin）
aidevops projects # 列出项目（* 标出当前项目）
aidevops use qa-copilot-platform # 选中项目，后续命令默认作用于它
aidevops status # 当前后端 / 账号 / 项目
是产品入口，缺任何一环后面的
commits /
risk /
explain 都是空态：
aidevops connections # 看现有 Git 凭据，拿 connection id
aidevops connection-add -l my-github -t <PAT> # 私有库需要 repo 读权限
aidevops connection-verify <connection-id> # 先验证凭据能用
aidevops repo-add -c <connection-id> -f owner/repo # 注册仓库
aidevops sync <repository-id> --wait # 拉取历史，跑完即用
connection 是
组织级凭据（管理员管理），一个凭据可注册多个仓库；
repo-update 能调同步窗口与模块归属深度。
升级用
aidevops upgrade。客户端每次运行都会比对 PyPI 最新版，落后了用红字提示（结果缓存 24 小时，
AIDEVOPS_NO_UPDATE_CHECK=1 可关）。一个防呆：
upgrade 在
pip install -e 的开发检出处
拒绝执行——那会把你的工作区悄悄换成发布版，提示你改用
git pull。
配置与令牌存用户配置目录（Windows
%LOCALAPPDATA%\aidevops\，Linux
~/.config/aidevops/），文件权限 0600。
十、脚本化与 CI
--json 是
全局选项，放在子命令之前：
aidevops --json findings | jq '.[] | select(.severity == "critical")'
两个为管道做的细节：
--json 模式下升级提示走
stderr，不污染 stdout；
AIDEVOPS_JSON=1 环境变量等价于全局 flag。CI 里用
AIDEVOPS_TOKEN 直接注入令牌（免交互登录），
AIDEVOPS_BASE_URL 指向测试后端做集成验证。
一个实际的 CI 场景：流水线里跑
aidevops --json risk $GITHUB_SHA，分数超过阈值就把关联的回归候选列表贴到 PR 评论里——风险引擎和 AI 建议都变成了流水线的一等公民。
十一、工程化：测试、类型、发布流
客户端在仓库的
cli/ 目录下，工程化配置是完整的：
python -m pytest # 50 个客户端测试，含 Textual pilot 的 TUI 测试
python -m ruff check .
python -m mypy ai_devops_cli
TUI 用 Textual 的 pilot 做交互测试——全屏应用的按键流、面板切换都覆盖到了，不靠人肉点。后端另有
569 个测试（4 个 network 用例默认跳过），全部不依赖外网，CI 上跑得飞快。
多租户的写路径全部收口在
scoped_queryset 唯一入口，配合上面说的 URL 租户语义，测试可以逐条断言「租户 A 永远看不到租户 B 的数据」。
PyPI 发布走
tag 触发的 trusted publishing 工作流：打 tag → GitHub Actions 构建 → OIDC 短期凭证上传 PyPI，没有本地打包、没有长期 token。
十二、现状、局限与 Roadmap
现在是
Alpha（Development Status 3），几个明确的局限：
- 需要自建后端：客户端离开后端没有独立价值，想试完整流程得先跑起服务端（docker compose 一套或本地 make 一套）；
- 单组织多项目已经支持，跨组织的权限模型还在收敛；
- 真实 LLM 端到端 smoke test 在 roadmap 上（当前 Agent 测试用桩模型，逻辑路径已覆盖，真实模型的输出契约待验证）；
- 模块归属解析需要按仓库配置一次覆盖规则，零配置的准确率依赖源根推断的质量。
Roadmap 优先级：终端详情视图补完 → 真实 LLM smoke test → Celery worker 生产形态验证。
如果你也在做 QA 平台，或者对「研发数据关联」和「有笼子的 AI Agent」这两个方向有兴趣，欢迎提 issue：
github.com/zhoujungis/ai_devops。装起来一行命令：
pipx install aidevops。