ARTICLE · 1363008
第17讲 实战项目源码解读 / 答疑番外——把 11 篇可运行片段,组装成一个能部署、能收钱的真实项目
本讲是专栏知识树「认知 → 平台 → 协同 → 工程化 → 商业化」的收官番外:前 16 讲我们一路从"什么是智能体"讲到"一人公司怎么合法、持续收钱",并在第15讲首次给出 OPC / PASM 的「示意」目录、第16讲给出一张把 08–16 讲代码串成可复制资产的「源码地图」。
读完你能带走四件事:① 一张 OPC 平台的真实目录地图(不再是"示意"),每个模块都能在仓库里
find到;② 三段真实节选的源码(后端入口 / 路由注册 / 画布内核),看清楚多租户、限流、合规、计费在代码里长什么样;③ 一套把第15讲opc_customer_service.py接进真实 FastAPI 路由的可跑骨架 + 一个核对仓库模块的自检脚本;④ 一份"番外·读者高频问答"与专栏收官清单。
一、引子·为什么:你手里是 11 篇片段,缺的是"把它们拧成一台机器"的最后一公里
先把进度条拉到底,确认你站在哪:
第01–06讲,你懂了"什么是智能体""它怎么感知—规划—记忆—工具—行动""提示词怎么写";
第07讲拆了扣子、第08讲可视化建出第一个 Bot、第09讲看了 Manus 的规划—执行—反思;
第10讲在低代码里编排多智能体、第11讲把团队写成 CrewAI / AutoGen / AgentScope;
第12讲用 LangChain 给单智能体盖了"编排/记忆/工具/状态/可观测"五层楼、第13讲把 Dify 引擎拆开;
第14讲收了工程化全链路(长期记忆/工具沙箱/规划循环/评测/可观测);
第15讲用 OPC + PASM 端到端跑通"一人公司"、第16讲收了商业化四闸(定价/升级/合规/留存)并给出源码地图。
到这里,专栏把"怎么造机器人 → 怎么开公司 → 怎么合法收钱"这条线讲透了——至少在原理层面。但第16讲结尾自己埋了个钩子:"你手里散落的是 10 篇可运行片段,还差最后一步:怎么把它们真正组装成一个能跑、能部署、能交到客户手里的完整项目?"
这一步,就是本讲的主角。
廖显东在《从0到1搭建AI智能体》里把"从技术到产品"称为智能体落地的"最后一公里",而本专栏第15/16讲讲的正是这公里的理论;但理论走到落地,中间还隔着"真实工程的熵":目录怎么分、路由怎么挂、多租户头怎么传、限流和合规放哪一层、部署前要不要先备库。这些细节,教科书不会写、低代码平台替你藏起来了,但一旦你要"自己握着编排权和数据"(呼应第15讲坑7"过度依赖单一平台"),就必须亲手翻开源码看清楚。
作者写《手把手教你搭建自己的AI智能体》那句被本专栏反复引用的"先想清楚卖给谁、再想清楚怎么造",落到本讲就是:你要把"卖给谁"落成真实的订阅路由(billing)、把"怎么造"落成真实的画布执行(canvas/core),而不是停留在片段层面。 而《OPC 落地手册》反复强调的"底座开源、模板收费"双轨,我在真实仓库里也找到了它的落点——marketplace 模块(见 2.3)。
举个最扎心的例子:第15讲你跑通了 customer_service,以为"一人公司"就成了;但真实仓库里它只是 api/v1/chat.py 下的一个员工,四周还站着 billing(怎么收钱)、compliance(怎么合规)、spaces(怎么隔离十家店)、marketplace(怎么把模板卖出去)。少了任何一环,你手里的就不是"公司",是"会聊天的脚本"——这正是前面 16 讲没在"一个文件"里同时摆出来的真相,也是本讲非读真实源码不可的原因。
一句话:前 16 讲给了你"零件手册",本讲给你"装配图纸 + 实地参观"。
二、原理·深入:OPC 平台真实目录地图 + 三本书对比背书
第15讲 2.5 给过一份 OPC / PASM 的"示意"目录,今天把 OPC 这份换成我在仓库里真实 find 出来的结构(路径 E:/AI/opc-platform,节点为作者实际落地形态,非逐行源码,仅目录与模块名真实):
2.1 OPC 平台真实目录(已核对)
E:/AI/opc-platform/├── backend/app/ # FastAPI 多租户后端(经营层落点)│ ├── main.py # 应用入口(lifespan 自举 + 洋葱中间件)│ ├── api/v1/ # 路由层:admin/agent/agents/auth/billing/│ │ # compliance/marketplace/spaces/projects/│ │ # chat/timeline/knowledge/references/│ │ # api_keys/integrations/...(共 28 个路由)│ ├── core/ # 业务内核:agents/billing/compliance/│ │ # plans/metering/ratelimit/security/│ │ # backup/audit/llm/...(共 30+ 模块)│ ├── db/ # base.py / session.py(连接池与 ORM 底座)│ └── schemas/ # 契约层:agent/agent_task/billing/│ # business/canvas/compliance/...├── frontend/src/canvas/ # WebGL 画布 + DAG 执行(前端落点)│ ├── core/ # canvasKernel.ts / graphExec.ts /│ │ # agentExec.ts / space.ts / billing.ts /│ │ # compliance.ts / knowledge.ts / ...│ ├── engine/ # 渲染引擎(节点/边/视口缩放)│ └── ui/ # 检查器 / 面板(含 CompliancePanel)├── admin/ # 运营后台(自举管理员入口)├── miniprogram/ # 小程序端(feed/tasks/my 等页面)├── docs/adr/ # 架构决策记录(真实工程纪律)└── docs/deploy/ # 部署文档(呼应第16讲"部署收钱")
看清这份地图,你会发现它和第15讲"经营单元 = 一张 DAG + 一群数字员工 + 一个事实层"是严丝合缝的:
frontend/src/canvas/core/graphExec.ts +agentExec.ts= 第15讲 2.2 的"WebGL 画布 + DAG 执行引擎"(节点契约 → 沙箱执行);
backend/app/core/agents.py = 第15讲 2.3 的"数字员工本体"挂载点;
backend/app/api/v1/spaces.py + 前端space.ts= 第15讲"多租户隔离"(X-OPC-Space头,见 2.2);
backend/app/core/billing.py +plans.py= 第16讲 3.2 的"订阅档位"真实落点;
backend/app/core/compliance.py + 前端CompliancePanel.tsx= 第16讲 2.3 的"合规四闸"真实落点;
backend/app/api/v1/marketplace.py= 《OPC 落地手册》"底座开源、模板收费"双轨的印证。
2.2 后端入口 main.py 精讲(真实节选,略有删节)
为什么从一个入口文件讲起?因为工程的"世界观"全写在它的中间件和生命周期里。下面这段是 OPC 平台 backend/app/main.py 的真实节选,我标了注释对应哪一篇:
# backend/app/main.py —— OPC 平台真实节选(略有删节)@asynccontextmanagerasync def lifespan(_: FastAPI):# ① 自举管理员:把 admin_email 对应账号提升为管理员(幂等)await get_user_store().ensure_admin(get_settings().admin_email)# ② 快照备份:启动补一次 + 后台定时循环(呼应"部署前先备库" pitfalls)await asyncio.to_thread(backup.snapshot_if_stale)backup_task = asyncio.create_task(backup.backup_loop())yieldawait engine.dispose() # 进程退出前干净关闭连接池def create_app() -> FastAPI:app = FastAPI(title=settings.app_name, version=settings.app_version,description="OPC 一人公司 AI 创作与经营平台 API",lifespan=lifespan)# ③ 洋葱中间件:CORS 白名单必须显式含 X-OPC-Space(多租户活跃空间标识)app.add_middleware(CORSMiddleware, allow_credentials=True,allow_headers=["Authorization", "Content-Type","X-Request-ID", "X-OPC-Space", "X-OPC-Key"])# ④ 限流中间件(呼应第14讲可观测 + 第16讲合规闸的"稳健收钱")app.add_middleware(RateLimitMiddleware,limiter=SlidingWindowLimiter(limit=settings.rate_limit_per_minute))# ⑤ 全局异常兜底:服务端留全栈日志,对外只给安全信息(防堆栈泄露)@app.exception_handler(Exception)async def unhandled_exception_handler(request, exc):logger.exception("unhandled_error ...")detail = f"{type(exc).__name__}: {exc}" if settings.debug else "内部服务错误"return _error_response(request, {"detail": detail}, 500, ...)app.include_router(api_router, prefix="/api/v1")return app
三个值得拍大腿的点,正好把前讲串起来:
X-OPC-Space这个自定义头—— 它就是第15讲"多租户隔离"在 HTTP 层的实体:浏览器对自定义头会发 CORS 预检,白名单漏了它,移动端直连就只看到 Failed to fetch。这解释了为什么第15讲说"多租户不是加个字段,是贯穿全链路的标识"。
RateLimitMiddleware+ 全局异常兜底—— 第14讲"可观测"和第16讲"合规四闸"的工程收口:限流防刷爆、异常兜底防堆栈泄露(PIPL 数据最小化同源)。
lifespan里的backup.snapshot_if_stale—— 这就是第15讲坑"不沉淀客户事实"的反面教材:平台自己先把"数据不丢"做进启动流程,作者都不敢裸奔,你更该照做。
2.3 路由注册表 router.py 精讲(真实节选)
第16讲 2.5 的"源码地图"承诺把 08–16 讲挂到真实模块上,下面这段 backend/app/api/v1/router.py 真实节选,就是那张"挂接表"的硬证据:
# backend/app/api/v1/router.py —— OPC 平台真实节选api_router.include_router(spaces.router, tags=["spaces"]) # 第15讲 多租户api_router.include_router(billing.router, tags=["billing"]) # 第16讲 3.1 定价api_router.include_router(compliance.router, tags=["compliance"]) # 第16讲 2.3 合规四闸api_router.include_router(agents.router, tags=["agents"]) # 第15讲 2.3 数字员工api_router.include_router(agent.router, tags=["agent"])api_router.include_router(chat.router, tags=["chat"]) # 第15讲 3.2 客服员工api_router.include_router(marketplace.router, tags=["marketplace"]) # 《OPC 落地手册》双轨api_router.include_router(timeline.router, tags=["timeline"]) # 第15讲 2.6 成片时间线api_router.include_router(knowledge.router, tags=["knowledge"]) # 第13讲 RAG 知识库api_router.include_router(api_keys.router, tags=["api-keys"]) # 第08讲 配置即代码
注意 marketplace 这一行——它印证了《OPC 落地手册》推荐的"底座开源、模板收费"双轨:核心编排权(OPC 这类底座)开源做信任与生态,上层"行业交付物模板"(如餐饮代运营)走 marketplace 售卖做收入。你第15讲辛辛苦苦攒的"客服/内容/记账/投放"四个员工,最终就是 marketplace 里的一个个可上架模板。
2.4 画布内核 frontend/src/canvas/core(真实文件清单)
第15讲 2.2 说 OPC 是"WebGL 无限画布 + DAG 执行引擎",这不是比喻,是 frontend/src/canvas/core/ 下的真实文件:
canvasKernel.ts—— 画布内核(节点/边的增删改 + 视口缩放,即第15讲"WebGL = 多租户缩放");
graphExec.ts—— DAG 执行引擎(拓扑排序 + 调度,即第10讲"主体 DAG 保稳定"的前端落点);
agentExec.ts—— 执行体(把节点 handler 送进沙箱跑,即第14讲 3.2 工具沙箱的前端孪生);
space.ts—— 多租户(每家店一张子图,呼应 2.2 的 X-OPC-Space);
billing.ts/ compliance.ts—— 前端计费和合规面板数据层(第16讲四闸的前端一半)。
2.5 PASM 事实层的位置(概念层回顾,真实认知层以你本地仓库为准)
第15讲 2.5 曾给出 PASM 认知层(memory/fact/routing/extractor/planner...)的"示意"结构。本讲主角放在 OPC,是因为OPC 是"经营层"的落点、PASM 是"认知底座"——前者直接对应你卖什么、怎么收钱,后者对应四个员工怎么"共用一个脑子"(第15讲 2.4)。PASM 真实仓库路径因你本地环境而异,本专栏以第15讲建立的"事实层 = 结构化断言 + 记忆路由"心智模型为准,不在此编造其目录;需要深入时,按第15讲 2.5 的思路去你本地 pasm/cognitive/ 对照即可。
2.6 三本书 + OPC/PASM 的对比背书表
维度 | 通用平台(扣子/Dify/Manus/CrewAI) | 三本书观点 | OPC/PASM 自研落点 |
多智能体编排 | 云端 SaaS / 库级 | 廖显东:编排是落地骨架 | OPC |
跨岗位记忆 | 平台内封闭 | 《手把手》:先想卖给谁再想怎么造 | PASM 事实层 + 记忆路由(第15讲 2.4) |
商业化计费 | 多数缺失 | 《OPC 落地手册》:档位即权益 | OPC |
合规闸门 | 平台替你担 | 三本都提"合规是底线" | OPC |
底座 vs 模板 | 一体封闭 | 《OPC 落地手册》:双轨 | OPC |
看清这张表:通用平台把"编排/记忆/计费/合规"卷进黑盒,三本书把它们讲成方法论,而 OPC/PASM 把它们变成你手里可读、可改、可握有的真实模块——这正是自研底座相对"全压在 SaaS"的终极护城河(第15讲坑7)。
三、实战·可运行:本地把项目跑起来,并把"员工"接进真实路由
这一节给你能直接动手的东西。环境同前:Python 3.10+,API Key 走环境变量(第08讲"配置即代码"底线)。
3.1 把第15讲的"客服员工"接进真实 FastAPI 路由(真实可跑骨架,复用第15讲 3.3)
第15讲 3.3 给了 opc_business_api.py,本讲把它和真实仓库的 api/v1/chat.py 路由风格对齐——真实项目里你的数字员工就是挂成一个 router:
# opc_serve_demo.py —— 把"客服员工"挂成 FastAPI 端点(真实可跑骨架)from fastapi import APIRouter, FastAPIfrom pydantic import BaseModelfrom opc_customer_service import customer_service # 复用第15讲 3.2router = APIRouter(prefix="/api/v1/opc", tags=["opc-demo"])class MsgIn(BaseModel):tenant: str # 多租户标识,呼应 2.2 的 X-OPC-Spacemessage: str@router.post("/serve")def serve(body: MsgIn):return {"tenant": body.tenant,"reply": customer_service(body.tenant, body.message)}# 真实仓库里等价于 backend/app/api/v1/chat.py 挂载方式;# 生产再加 X-OPC-Space 头校验 + 限流(见 2.2),本骨架从简。app = FastAPI()app.include_router(router)
pip install fastapi uvicorn langchain-openaiuvicorn opc_serve_demo:app --port 8000curl -X POST http://127.0.0.1:8000/api/v1/opc/serve \-H "Content-Type: application/json" \-d '{"tenant":"王家小馆","message":"今天营业到几点?"}'
3.2 真实仓库本地启动(以仓库 README 为准,此处为通用步骤)若你 clone 了作者真实仓库,启动方式是标准的,但依赖与入口以你本地 README 为准,不在此编造命令:
# 示意:通用启动流程,真实参数见仓库 README / docs/deploy# cd backend && pip install -r requirements.txt# uvicorn app.main:app --host 0.0.0.0 --port 8000# cd ../frontend && npm install && npm run dev
核心价值:第15讲 3.2 的 opc_customer_service.py 是"员工本体",本讲 3.1 把它挂进"经营路由",而真实仓库的 app.main:app 是"整家公司"——你从片段走向完整项目,差的只是这一步"include_router"。
3.3 仓库模块自检脚本(真实可跑:核对你本地 OPC 是否含本讲提到的关键模块)
把"读源码"变成"可验证动作"——下面这段跑在你本地,能断言本讲讲到的关键文件是否真实存在(呼应第14讲"评测集"的工程化思维):
# verify_opc_layout.py —— 核对 OPC 仓库关键模块(真实可跑)import os, globREPO = os.environ.get("OPC_REPO", r"E:/AI/opc-platform") # 以你本地为准EXPECT = ["backend/app/main.py","backend/app/api/v1/router.py","backend/app/core/billing.py","backend/app/core/compliance.py","backend/app/api/v1/marketplace.py","frontend/src/canvas/core/graphExec.ts","frontend/src/canvas/core/agentExec.ts",]missing = [p for p in EXPECT if not os.path.exists(os.path.join(REPO, p))]print(f"仓库根:{REPO}")print("缺失模块:" + (", ".join(missing) if missing else "无,全部命中 ✅"))print(f"canvas/core 文件数:{len(glob.glob(os.path.join(REPO,'frontend/src/canvas/core/*.ts')))}")
跑起来若全命中,说明你本地仓库与本文地图一致;若某些路径不同,以你本地仓库为准——本讲给的是"读源码的方法",不是"必须照抄的路径"。
3.4 部署收钱的最小闭环(示意,非逐行真实接口)
从本地到"能收钱",链路是:本地跑通(3.1)→ 自有域名 + HTTPS → 过第16讲闸2(ICP 许可证 B25 类)→ 订阅档位(第16讲 3.2 SUBS 写进 PASM 事实层)→ 计费 webhook(billing 模块,示意)→ 交付物推送(第15讲 3.4 package_monthly_report)。其中合规与计费的真实接口以仓库 compliance.py / billing.py 与你当地主管部门口径为准,本文不编造参数。
四、避坑·衔接:源码解读与部署的九个坑 + 番外问答 + 专栏收官
按踩到的概率排序:
- 只读片段不读 DAG(最高发)
。以为会写 customer_service就会做平台,结果漏了graphExec.ts的调度语义。对策:先读canvasKernel.ts→graphExec.ts→agentExec.ts这条链(呼应第15讲 2.5)。 - 多租户忘带
X-OPC-Space。本地 PC 同源没暴露,上线移动端直连就 Failed to fetch。对策:CORS 白名单 + 后端校验都带上它(见 2.2)。 - 合规只做后端不做前端
。后端 compliance.py有了,前端没CompliancePanel,客户看不见隐私告知。对策:合规是双向的,第16讲四闸前后端都要落。 - 把
marketplace当摆设。双轨只开源不收费,或只收费不开源,都没吃到《OPC 落地手册》的护城河。对策:底座开源做信任,模板上架做收入,二者都动。 - 不读
*.test.ts当真相。canvas/core 下每个模块都有 .test.ts(如graphExec.test.ts),那是作者给自己定的"契约测试"。对策:读源码先读测试,比读文档快三倍。 - 直接跑生产库不备
。忘了 lifespan里的backup.snapshot_if_stale。对策:上线前先确认备份循环在跑,数据不丢优先于功能炫。 - 忽略
lifespan自举。以为 ensure_admin可有可无,结果运营后台登不进。对策:自举是幂等的,照抄即可,别删。 - 把"示意"当"真实接口"
。第15讲 opc_executor_sketch.py标了"非逐行真实源码",有人却拿它当 OPC 内部 API 调。对策:凡标"示意"的,落地前回真实仓库核对。 - 不装依赖直接
uvicorn。漏了 requirements.txt/npm install,启动即ModuleNotFoundError。对策:3.2 的"以 README 为准"不是客套,是第一步。
选型决策(文字版):想验证"能不能卖" → 第08/10讲低代码跑一个岗位;验证能收费 → 第15讲 OPC 画布编排四个员工;要做到数据自主、可管十家店以上 → 上 PASM 事实层(2.5)+ 真实仓库多租户(2.2);要合法规模化 → 必过第16讲四闸(主体/ICP/备案/PIPL),并参考《OPC 落地手册》部署。一层一层加,和第14讲"渐进加工程化"、第15讲"框架是杠杆不是枷锁"节奏一致——别第一步就 clone 整个平台。
番外·读者高频问答(Q&A)
Q1:没有营业执照能做一人公司吗? A:第16讲闸1 说得很硬——能合法开票、收钱的前提是经营主体(公司或个体工商户,如作者"寰霖汇商贸个体工商户")。纯个人收钱走个人码,规模化必踩合规。先注册再收钱。
Q2:OPC 和 Dify 怎么选,不冲突吗? A:不冲突,是"同源不同层"。Dify 是单应用工作流(第13讲),OPC 面向"公司经营"(多租户 + 多员工 + 计费 + 合规)。小验证用 Dify,要自己握数据和商业化闭环用 OPC;OPC 也可把 Dify 当某个节点的能力补充。
Q3:PASM 事实层必须自己造吗? A:不一定。第15讲 2.4 的"结构化事实 + 路由"心智模型可直接用 SQLite/Postgres 实现(第15讲 3.2 LongTermMemory 就是最小版)。等你管十家店以上、要冲突消解时,再上完整 PASM 认知层。
Q4:一个人维护得过来这么大的仓库吗? A:OPC 的 docs/adr(架构决策记录)和 *.test.ts 契约测试,正是为"一人维护"设计的——把决策和契约固化成文件,你半年后回来仍能接上。这正是《手把手教你搭建自己的AI智能体》"可维护优先于可炫"的工程体现。
Q5:源码哪里开源、模板怎么收费? A:以仓库 marketplace 模块与《OPC 落地手册》"双轨"为准:底座(OPC/PASM 这类编排权)开源做生态信任,行业模板(如餐饮代运营四员工)上架收费。具体上架形态以你本地仓库与平台规则为准。
专栏收官(第17讲为收官讲,下一编号 18 已超出大纲上限,自动化续写将在此停止): 本讲从"真实仓库"而非"示意目录"出发,把 OPC 平台的 main.py(多租户头/限流/备份自举)、router.py(billing/compliance/marketplace/agents/spaces 真实路由)、canvas/core(graphExec/agentExec/canvasKernel 真实文件)逐一串讲,并给了"员工接路由"的可跑骨架与"仓库自检脚本"。至此,专栏知识树「认知 → 平台 → 协同 → 工程化 → 商业化」五段完整闭合:你从"懂智能体"(01–06),走到了"能自己握着编排权和数据、合法持续收钱的真实项目"(17)。 三本书的对比背书与 OPC/PASM 的工程落地,也从"概念"落到了"可 find 到的代码"。
学习节奏建议:本讲 3.3 的
verify_opc_layout.py建议真在你的机器上跑一遍——把OPC_REPO指向你本地仓库,亲眼看到"全部命中 ✅",比读十遍地图都实在。跑之前,回第15讲把opc_customer_service.py(3.2)和第16讲把合规四闸(2.3)再读一遍,本讲是它们的"装配现场",对照着看,从片段到完整项目的最后一公里才算真正走通。
本讲完,亦专栏主线收官。若读者反馈踊跃,作者会在大纲「17+(可选)实战项目源码解读 / 答疑番外」槽位继续增补专题番外;自动化续写按大纲上限,于 next=18(>17)时自动停止,届时请小志补充新主题后再启动。OPC 一人公司平台(WebGL 画布 + DAG + 多租户)与 PASM 认知引擎(事实层 + 记忆路由)的真实源码地图,至此从"示意"升级为"可验证"。感谢你陪跑这 17 讲——从造机器人,到开公司,再到合法、持续收钱。















































































