这是一份二合一附录。前半部分基于 git log 全量分析 419 个 commit,复原从 3-19 首个 commit 到 6-24 交付的完整时间线、5 个真实开发者画像、以及 .NET 中途上场的技术判断——回答"这个项目怎么来的"。后半部分基于 web/src/routes.tsx(180 行单一权威源)+ 实际点开每个菜单获取的 UI 结构,画出 4 大板块 · 25 个功能页 · 8 个任务流程 · 13 个 Agent 的完整地图——回答"这个系统有些什么"。
项目是怎么来的——时间线 · 五幕故事 · 十次艰难时刻 · 五个开发者手艺画像 · 一次关键技术选型。
419 commits · 5 人参与 · 4 个月挂在日历上。fix 和 feat 比几乎 1:1——bug 密度高、迭代快，是"边打边跑"的项目节奏，不是"设计好了慢慢做"。
按周统计 commit 数——项目节奏呈现 W16 / W17 / W19 三个爆发峰，中间有短暂的降速期，最后 W26 只有 3 个 commit 且全是"上传交付材料"，标志开发实质结束。
下面每一幕都是从 git log --author + --pretty=format --oneline 挖出的真实 commit 序列，不是叙事包装。每个引号里的都是原文 commit message。
3/19 首个 commit 直接是 initial commit，但第二个 commit 就是 新增技术分析文档，概述项目定位、核心功能、实现原理及技术难点——项目从一开始就有先思考再动手的习惯。
3/26 一周内跑出 feat: Docker化部署 + Azure OpenAI Embedding 支持——基础环境速度极快。4/3 已经开始 refactor(api): complete I2 port-adapter convergence，说明从脚本原型切到Hexagonal 架构只用了两周。
4/6 有一次老练操作：在 feat: migrate document jobs to redis worker service 之前，先打了个 baseline before redis job service migration 作为回滚锚点——改大件前留备份是本项目全程的习惯。
W16 是整个项目最忙的一周——58 个 commit。核心是把"能跑的原型"变成"能上生产的工程"。
4/14 架构日——一天完成 5 件大事：SQLite → PostgreSQL、db 目录改名 db_migration、拆 shared 层（把 db/storage/llm/queue/cache/retrieval 从 api 里挖出来）、简化 API 架构、以及一个关键 refactor consolidate ports, usecases, middleware; remove dead code & stale docs。不惜工本清理死代码是本项目的技术文化。
4/15 出现整个项目最重要的产品原则 commit：feat: 优化回答的正文中的角标处理逻辑 如果用户的提问，在已有知识来源中未找到，应拒绝回答，而不应让大模型自我发挥——忠实性从这里开始被硬化到代码里，一直贯穿到最终的 skill prompt。
4/16 第一次事故：revert dockerfiles before cython so build——Cython 编译搞崩了，回滚。这是项目全期仅 3 次 revert 中的第一次。
4/20 转折日：一天两件大事——feat: docker-compose 集成 .NET 后端 + 前端全量迁移至 V3 API 和 feat(pikerag-net): V3 全量迁移 — Phase 2-F + 前端 V3 适配 + Python 路由清理。.NET 进入战局，V3 开始接管全局。
4/25 打 checkpoint：checkpoint: before V3 agent optimization (prompt compact + multi-turn fix)——大改前先存档，前面必有 close call。
4/28 里程碑日——三件事：ChromaDB → Milvus 迁移完成 · 知识湖仓 Lakehouse 架构设计 · Curation Pipeline 上线（一个 commit 800+ 行 changelog，PDF/Word/Excel/PPT/Markdown 全支持 + 4 个 NuGet 安全漏洞、路径遍历、竞态条件同时修复）。这一个 commit 抵得上别人一周的工作量。
5/5 事故日——DB migration v0025 缺列，同一坑连踩两次到 v0026；v0037/v0038 迁移编号撞车；PG DateTime 时区兼容性。这天有 6 个 fix commit——把 .NET 的 EF migration 也全部搬到 Python Alembic 里，统一迁移工具链。
5/7 前端崩：fix: PublishedAgentPage infinite update loop——修完还有 bug，同一天二次修复。
5/8 换工作流引擎：feat: Elsa workflow engine migration——之前用的不合适，换掉。
5/13-14 向量化性能大修：fix: vectorization performance remediation (GPU + batch embedding + dispatch idempotency)——GPU 利用率从 0% 提到 100%，78 chunks 从 242 秒 缩到 <2 秒（周报也印证了）。同一天还有 perf: refactor Elsa Activities to eliminate TOAST bloat (S3-as-IPC)——workflow state 撑爆 PG 的 TOAST，被迫把中间态改成 S3 存。
5/14 A100 也 OOM：fix: robust adaptive split for embedding OOM (catch generic 500, pre-check tokens before sending)——单批过大炸了 GPU，做了自适应切分兜底。
5/22 qa-harness 落地：feat(agentic): qa-harness agent, context tools, skill DB-first loading——从 workflow 模式切到 Harness 模式（LLM 动态决策）的转折点。
5/25 GraphRAG 大整改：修 Cache Key 加 KB ID（跨 KB 缓存污染）· O(n²) 改 O(1) · 孤儿关系日志 · maxTokens 8192 · JSON ResponseFormat 全链路——一次 commit 修 5 个不同层次的问题。同一 commit message 出现了两次，说明 push 出问题重发。
5/27 密钥危机：feat(db-migration): add llm_backend protocol column migration——生产用的 service account key 3 个月过期，被迫申请两个 key 做轮换切换协议列（周报 R6 也记录了）。
6/1 一天 3 次反复：feat(agentic): emit structured summary as dedicated SSE event (ISSUE-003) → feat(agentic): add summary option to agent post-processor select (ISSUE-003) → revert(agentic): 回退结构化摘要方案，改用 Markdown 标题渲染 (ISSUE-003)——设计反复到最终回退简单方案。项目全期最后一次 revert。
6/3-4 Nomad 切换：fix(gateway): route /api/v1/ to .NET adapter——旧 docker-compose 应用彻底下线，Nomad 独占标准端口。周报里 06-03 记录的"旧应用下线 · pikerag-embedding.service 已 disable"就是这个 commit。
6/9 ISSUE-012 闭环：docs(issues): ISSUE-012 转 closed，回归验证通过修复闭环——项目有正式的 issue 追踪流程（docs/issues 目录）。
6/11-13 Secret 大扫除——连续 8 个 commit 全在做同一件事：remove postgres password literals · remove hardcoded dev credentials · shorten dummy apiKey below secret-scanner threshold · replace remaining truncated example JWTs with placeholders。上线合规扫描前的清剿——gitleaks 扫过。
6/19 GKB Go Live 前的最后精调——一天 3 个 skill 提示词修复：fix(skill): 优化答案忠实性与缺失处理 · fix(skill): 优化术语规范 · fix(skill): 优化答案编写技能的提示词。项目最后的技术活是提示词精调，不是代码。
6/24 三个 commit 都是上传交付文档：upload project documents · Added file · Added Project Delivery Doc——开发实质结束，进入交付验收。
下面列出的是会让开发者半夜爬起来处理的时刻——性能爆表、依赖崩了、迁移事故、密钥过期。每条都有 commit SHA 或 commit 序列可查。
vectorized_at 列没加 guard 崩了；改完打 v0026 又忘加 guard，同 bug 再爆一次。fix: v0026 migration also needs vectorized_at guard (duplicate of v0025 issue)catch generic 500, pre-check tokens before sending 兜底。 perf: refactor Elsa Activities to eliminate TOAST bloat (S3-as-IPC)fix: PublishedAgentPage infinite update loop 和 PublishedAgentPage infinite loop and Playground undefined agent。revert dockerfiles before cython so buildrevert: restore local document-intelligence in root docker-compose.ymlfeat: Elsa workflow engine migration + kb-tasks UI improvementsmulti-hop-retrieval skill 打补丁但根本设计未落地。add llm_backend protocol column。周报 R6 记录。读法：红色 = 事故（外部因素引发，如 OOM、依赖崩、密钥过期）· 橙色 = 设计问题（架构选型偏差、需求反复）· 金色 = 战术回撤（试了不 work，回退）。10 次艰难时刻 · 3 次 revert · 1 次同坑连踩 · 1 个持续 11 周未闭风险——考虑到 3 个月 419 commit 的节奏，这个"痛感密度"处于正常压力项目区间，不算灾难。
从 git log --author 分组统计每人真实修改的文件路径、次数、类型，交叉验证 commit message 风格与 code 层面证据（Python 96% 有类型注释 · CQRS 分层深 · 71 个 DB 迁移 · 77 个 YAML 配置），可以给出基于事实的开发者画像——不是印象。
① 架构洁癖极强——commit message 里有大量 refactor（37 个 refactor · 全项目 44% 来自他）。典型如 refactor: complete I2 port-adapter convergence、refactor: extract shared modules、refactor: simplify api architecture · consolidate ports, usecases, middleware; remove dead code——拒绝屎山、持续清理。
② 提交粒度大 · 一次 commit 覆盖多维度——典型如 feat: Curation Pipeline — Lakehouse 湖仓策展管线 (Step 1-10, 12) 一个 commit 涵盖后端 + 前端 + 迁移 + 安全修复共 800+ 行 changelog。做大事的时候能一次做完，但也让 diff 难 review。
③ 命名严谨 · 版本意识强——项目里 71 个 DB 迁移编号 v0001-v0071 全部整齐，refactor: rename pikerag-net → pike-agent, unify Pike.* namespaces 这种"改名"级重构他敢做——命名规范到愿意为了统一改名字重刷 100+ 文件。
④ 灾备意识——每次大动前打 checkpoint：checkpoint: before V3 agent optimization、feat: baseline before redis job service migration——先备份再动土。
⑤ 全栈技能真实——同一周内改 4447 行 C#、1178 行 TypeScript、457 行 Python，跨 pikerag-net 后端 + web 前端 + Python api + Helm + docker-compose——不是"会用"，是"活跃修改"。
refactor(graphrag): convert internal agents to builtin, remove internal typerefactor: rename pikerag-net → pike-agent, unify Pike.* namespacesfeat(graphrag): M1 project skeleton + DB schema + DI + frontend tab
在成熟工程师的标尺上，Yong Ma 大致处于 Staff Engineer / Tech Lead 段位——能独立设计一个中型企业级平台（55K 行 · 18 模块 · 双栈 · 双 namespace 部署）· 有清晰的分层意识（Hexagonal / DDD / CQRS 混合）· 熟悉多语言运行时（.NET Aspire + Python FastAPI + React Vite）· 对迁移工具链、可观测性、部署编排都亲自操刀。短板：单点风险高（56% 占比意味着他休 2 周整个项目慢下来）· 大 commit 让代码 review 变难。
① Skill 提示词专职——修改最多的文件是 mvr-grounded-answer/v1.skill.yaml（9 次修）。commit message 明显偏"提示词工程"味道：fix(skill): 优化答案忠实性与缺失处理、fix(skill): mvr-grounded-answer 摘要改为无条件第一块，去掉漏摘要逃逸口、refactor(skill): 反揣测规则瘦身 + few-shot 全抽象化——他懂 LLM 会怎么钻空子并把空子闭上。
② 部署运维——deploy/docker-compose/vm/customer/*.yml（客户环境部署模板）· 02-install-embedding.sh（部署脚本）· deploy/nomad/Makefile——生产部署他管一半。
③ Message 风格中文倾向——commit 里大量中文正文：fix(knowledge/v1): 文档写操作错误码细分 409→409/410/411/412/413、refactor(knowledge-v1): retry 删除判定简化为单道 IsDeleted guard——细节控 · 关注 API 契约的错误码语义。
④ Issue tracking 参与——docs/issues 30 行修改都是他的，ISSUE-003 反复、ISSUE-012 闭环都有他签名——做 QA / bug 闭环。
fix(skill): mvr-grounded-answer 摘要改为无条件第一块，去掉漏摘要逃逸口fix(knowledge/v1): 文档写操作错误码细分 409→409/410/411/412/413feat(agentic): 双语 narration + SSE progress/status 双通道
Senior Engineer 段位——不是全栈架构师，是垂直深耕型：LLM prompt 工程、backend 细节（错误码/幂等/重试语义）、DevOps 部署脚本三条腿。在这个项目里他和 Yong Ma 的分工是他做"活的东西"（业务规则、提示词、部署）——Yong Ma 做"骨架"（架构、迁移、双栈）。
① Nomad + Terraform + vLLM 主专家——deploy/nomad · src/vllm · deploy/cicd 三个目录几乎全是他改的。他是把生产 GPU VM 从 Azure ACR 到 vLLM 到 Nomad 全套跑起来的人。
② Secret 大扫除专职——12 个 commit 里 8 个是 replace remaining truncated example JWTs with placeholders · chore: remove postgres password literals · test: shorten dummy apiKey below secret-scanner threshold——gitleaks 合规扫描的清剿全在他手上。
③ CI/CD 制品管道——feat(cicd): add staging/TST image build configs for ECR、docs(cicd): add staging image pull/use guide——做企业级 CI 的老手。
chore: remove postgres password literals from compose connection stringsfeat(cicd): add staging/TST image build configs for ECRdocs(cicd): add staging image pull/use guide with third-party image manifest
Infra Specialist / SRE 段位——commit 量不多但每个都精准聚焦 CI/CD/合规。典型的"隐形保底"角色——项目做产品的顺，是因为有他把部署链路和合规扫描做稳了。
微软官方 PIKE-RAG 框架方顾问。3 个 commit——说明微软官方对项目的 hands-on 支持极浅，PIKE-RAG 底层 bug 更多是团队自己在处理。
单个文档 commit——路人。
与 chewa-git 共用邮箱 lulali@outlook.com——同一个人的另一个 git 身份。
2026-04-20 · Yong Ma 一天之内做了这个项目最大的技术选型决定——把 Python 主导的架构切成 Python + .NET 双栈。这个决定合理吗?是"个人偏好"还是"技术判断"?Python 一路到底是不是更好? 用代码里的证据来回答。
fd114b7这不是"心血来潮"——Yong Ma 一天推了 838 行 C# 重写分析文档 + 完整 Clean Architecture 骨架 + `.editorconfig` 382 行 + `Directory.Packages.props` 52 行。深思熟虑后的决定——且他有一天推出全栈模板的能力。同一天下午 docker-compose 集成 .NET 后端 + 前端全量迁移至 V3 API,次日 V3 全量迁移 — Phase 2-F + Python 路由清理。一周之内完成主战场切换。
项目从 initial commit 起就绑死 Azure 全家桶——OPENAI_API_TYPE="azure" · AZURE_OPENAI_ENDPOINT · AZURE_DI_API_KEY(Azure Document Intelligence)。交付方是 Microsoft Industry Solutions(每份周报封面),客户是 AZ China R&D,底层框架是 Microsoft/PIKE-RAG(所有 src/pikerag/*.py 头部 Copyright (c) Microsoft Corporation)。
ASP.NET Core / EF Core / Aspire / OpenTelemetry 都是微软最新一代技术栈。用 .NET 交付给 AZ = 微软内部的政治正确 + 客户 IT 团队的运维习惯。
看 Directory.Packages.props:
Microsoft.Agents.AI 是微软 2025 主推的官方 Agent 框架——对标 LangChain,但 .NET 是一等公民,Python 版功能滞后。项目要做 Agentic Harness(13 Agent × 6 Skill),而且要跟客户微软战略保持一致——用 LangChain 客户不认(不是微软 stack),用 Python 版功能落后半年到一年。
Yong Ma 前 30 天都在 Python 上写 (3/19 → 4/19):Hexagonal 架构 ✓ · BM25+Chroma+多轮 Planner ✓ · SQLite→PG 迁移 ✓ · Redis job 队列 ✓——都做出来了。
但 4 月中撞了硬墙:
• CQRS 分层复杂度上来后,Python 类型系统撑不住(即使 96% 类型注释,也没有编译期保证)
• Curation Pipeline 要处理 PDF/Word/Excel/PPT 五种格式——.NET 的 OpenXml SDK 官方支持一步到位;Python 的 python-docx/python-pptx/openpyxl 分散、老、坑多
• 企业级 Modular Monolith + CQRS + DDD 是 .NET 圈的老家饭——MediatR / FluentValidation / EF Core / Ardalis.GuardClauses 开箱即用,Python 没有对等物
39743e9)完成 Curation Pipeline 全栈——PDF/Word/Excel/PPT/Markdown 5 种解析器,.NET 生态一步到位制药大厂的技术栈标配是 .NET / Java——AZ 内部 IT 团队接手运维时,交给 .NET 后端他们熟悉;交给 Python 后端会哭。
看部署材料清单:Azure Container Registry + Aurora PostgreSQL + EF Core + Nomad + Terraform + OpenTelemetry → Grafana LGTM——这套栈客户 IT 用起来毫无学习成本。
结论:.NET 交付 = 客户长期能自己接手;Python 交付 = 长期依赖交付方——对 POC 转产品阶段是致命考量。
Yong Ma 明显更懂 .NET:4447 行 pikerag-net(C#) vs 457 行 src/api(Python) —— 差 10 倍。引入的模板是 jasontaylordev/CleanArchitecture —— 这是 .NET 社区最有名的 Clean Architecture 参考,不是随手找的。CQRS 分层做到每个 Command/Query 独立文件夹——.NET DDD 圈的标准做法,Python 圈几乎没人这么做。
但要区分:他不是"因为个人偏好选了 .NET"——项目起手用的是 Python,他先在 Python 里跑了 30 天。他是"识别到微软官方路线图 + 客户交付要求 + Python 撑不住企业级复杂度"后主动改选 .NET。他确实精通 .NET 才敢做这个决定——不熟悉的人不会一天推 838 行分析 + 全套 Clean Architecture 模板。
按 9 个维度对比——绿=胜出,红=不足,橙=折衷。判断"这个项目"里哪种更好。
双栈是最优解,不是败笔。当前分工:
Python 侧保留:
.NET 侧接管:
对于其他场景,答案可能反过来:
"本可以更好"的替代方案其实是:从第一天起就用 .NET,不要绕道 Python——省掉 3 个月的遗留清理。但这条路的问题是:PIKE-RAG 底层框架就是 Python,必须先用 Python 验证概念,才能有底气外层用 .NET 重构。
.NET 上场既不是随意也不是偏好——是识别到3 个硬约束后的判断:①微软 Agent AI 框架在 .NET 上先落地 · ②客户 IT 团队要能接手长期运维 · ③企业级 CQRS/DDD 复杂度 Python 撑不住。
Yong Ma 的价值不在于"他喜欢 .NET",而在于他先用 Python 跑了 30 天,发现撑不住,然后有能力一天推 838 行分析 + 全栈 Clean Architecture 模板迁到 .NET——这是成熟技术领导者的判断力,不是开发者的兴趣偏好。路径依赖决定了现在这个双栈状态是"必要的成本",不是"设计失误"。
TEAM这个团队本质上是三个人的小团（Yong Ma 全栈 · ShuaiHua Du 提示词/DevOps · chewa-git CI/CD/合规）——加上一个几乎没露面的微软顾问。没有 QA、没有专职前端、没有独立产品经理——需求直接对客户，实施靠三条腿。
SKILL技术水平 整体在企业级中上——不是花架子团队。证据：Python 96% 类型注释、71 个 DB 迁移编号整齐、CQRS 分层深到每个 Command/Query 独立文件夹、有正式 issue 追踪流程（docs/issues）、上线前做 secret 大扫除、Elsa/Nomad/vLLM/Milvus 生产级选型全在跑。这不是"能跑就行"的原型级手艺。
RISK最大结构风险是 Bus Factor = 1——Yong Ma 独扛 56%，横跨 .NET 后端 4447 行 + 前端 1178 行 + Python 457 行。他一个人的技术判断决定了：3 代 Retriever 演进、V2/V3 双栈、Elsa 换 workflow、Milvus 从 Chroma 换掉。他休一个长假，整个项目节奏会明显慢下来。
STYLE代码风格特征鲜明：Yong Ma 大 commit 猛推架构变革，ShuaiHua Du 小 commit 精修业务规则。commit message 一半中文一半英文——中文用在业务和 skill 修复上，英文用在架构和技术层重构上。这不是随机——"和 LLM 交流的语言 vs 和其他工程师交流的语言"分开，是一种主动的沟通习惯。
CULTURE项目文化偏向 "过度工程 + 快速试错"混合体——一方面能一次 commit 修 5 类问题、上线前做 Secret 扫描清剿、正式 issue 闭环追踪（这是过度工程一面）；另一方面又能同一天 3 次 revert、v0025 v0026 同坑连踩、Elsa 中途换掉（这是快速试错一面）。他们不追求完美，追求"能推动前进"。
FINAL如果要接手：优先跟 Yong Ma 做知识转移，把他脑子里没写在文档里的隐性判断（为什么选 Milvus / 为什么保留 V2 Python / Chroma 会不会真的下线）掏出来。ShuaiHua Du 的 skill 提示词是业务价值的核心资产——他做的忠实性硬约束、反揣测规则、few-shot 抽象化，直接决定了产品的临床合规可信度，是无法快速被替代的部分。chewa-git 的 Nomad + vLLM + CI/CD 是"隐形保底"——不出事你看不到他的存在，一出事只有他能修。
这个系统有些什么——4 大主菜单 · 25 个功能页 · 8 个内置任务流程 · 13 个 Agent 全清单 · 页面间依赖关系。
整个后台围绕四条主线组织:知识管理(数据入口 · KB / 文档 / 术语)· 智能体(业务逻辑 · Agent / Skill / Chat)· 系统(基础能力 · Gateway / 身份 / 模型仓)· 开发工具(基础设施调试 · 流程编辑器 / DB / 存储)。上层依赖下层,越靠上业务价值越高。
下面按四大板块逐一列出每个页面的:做什么(用户视角)· 与谁关联(上下游依赖)。这样能看清"哪个页面动了会影响谁"、"完成一件事需要走哪些页面"。
这张图把上面所有页面按业务价值层次排列——顶层是用户直接用的东西(智能对话 · 评测),底层是基础设施(Milvus · PG · S3)。用一根线连起来就是:用户在智能对话发问 → 命中Agent → Agent 调 Skill / Tool / KB → KB 查 Milvus → LLM 走 AI Gateway。
下面 3 个是最常见的操作路径。看这几张就能理解整个系统的用法闭环。
底层触发的任务流程:知识入库主流程 → 湖→仓 → 仓→向量 → 文档画像(dev 里能看拓扑)。验召回不满意 → 加术语表或调 KB 检索配置(dense/sparse/hybrid)。
先系统层把 LLM 后端(Gateway Pool)接好 → 再业务层写 Skill(说明书)/ Tool(动作)/ Agent(组合体)→ 最后用户层去 Chat 试。Skill 是最需要打磨的一环——项目的 mvr-grounded-answer skill 反复迭代了多次(见主报告 Act 5)。
评测本身也是一个内置工作流——数据集加载 → 逐条评估 → 汇总指标。关键动作是对比:新 Skill run vs 旧 Skill run,看是否退化。如果 recall 下降超过阈值 → 不上线。
从 UI 里扫描到的实际 Agent 清单——3 类角色:2 个业务主力(用户直接调)· 3 个文档处理(入库时自动调)· 8 个 GraphRAG 内部(图谱构建时自动调)。只有"业务主力"这一类是用户手动挑选去 Chat 的,其他都在后台自动跑。
src/pike-agent/src/Modules/Pike.Agentic/Definitions/agents/)。这些是 Elsa Workflow 定义的系统级流程——数据入库、评估、GraphRAG 抽取都由它们驱动。用户不用直接接触,但业务流程都靠它们跑通。
① 整个后台围绕一件事:让 Agent 能好好回答问题。所有其他菜单都是给这件事服务的支持系统。
② 数据 → 能力 → 编排 → 用户 四层清晰:KB / Milvus / S3(数据)→ Gateway / 术语表(能力)→ Skill + Tool + Agent(编排)→ Chat / 评测(用户界面)。
③ Skill 是最需要打磨的一环。修 Skill 提示词 → 跑评测 → 对比 → 决定是否发布,这是迭代 AI 效果的主循环。
④ 13 个预置 Agent 里只有 2 个是"业务主力"(mvr-pharma / kb-workflow-qa),其他都是后台自动调的处理 Agent——用户不用手动碰它们。
⑤ 开发工具那 5 个页面是"备用逃生梯"——正常运行不用点开,出 bug 时直接查 PG/Milvus/S3/Hangfire 是最快诊断路径。