夜雨聆风学习资料网

ARTICLE · 1363008

第17讲 实战项目源码解读 / 答疑番外——把 11 篇可运行片段,组装成一个能部署、能收钱的真实项目

第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())    yield    await 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

三个值得拍大腿的点,正好把前讲串起来:

  1. X-OPC-Space 这个自定义头
     —— 它就是第15讲"多租户隔离"在 HTTP 层的实体:浏览器对自定义头会发 CORS 预检,白名单漏了它,移动端直连就只看到 Failed to fetch。这解释了为什么第15讲说"多租户不是加个字段,是贯穿全链路的标识"。
  1. RateLimitMiddleware + 全局异常兜底
     —— 第14讲"可观测"和第16讲"合规四闸"的工程收口:限流防刷爆、异常兜底防堆栈泄露(PIPL 数据最小化同源)。
  1. 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 graphExec.ts + 第11讲三件套

跨岗位记忆

平台内封闭

《手把手》:先想卖给谁再想怎么造

PASM 事实层 + 记忆路由(第15讲 2.4)

商业化计费

多数缺失

《OPC 落地手册》:档位即权益

OPC billing.py + plans.py(第16讲 3.2)

合规闸门

平台替你担

三本都提"合规是底线"

OPC compliance.py + 前端 CompliancePanel

底座 vs 模板

一体封闭

《OPC 落地手册》:双轨

OPC marketplace.py(开源底座+收费模板)

看清这张表:通用平台把"编排/记忆/计费/合规"卷进黑盒,三本书把它们讲成方法论,而 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-Space    message: 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 与你当地主管部门口径为准,本文不编造参数。


四、避坑·衔接:源码解读与部署的九个坑 + 番外问答 + 专栏收官

按踩到的概率排序:

  1. 只读片段不读 DAG(最高发)
    。以为会写 customer_service 就会做平台,结果漏了 graphExec.ts 的调度语义。对策:先读 canvasKernel.ts → graphExec.ts → agentExec.ts 这条链(呼应第15讲 2.5)。
  2. 多租户忘带 X-OPC-Space
    。本地 PC 同源没暴露,上线移动端直连就 Failed to fetch。对策:CORS 白名单 + 后端校验都带上它(见 2.2)。
  3. 合规只做后端不做前端
    。后端 compliance.py 有了,前端没 CompliancePanel,客户看不见隐私告知。对策:合规是双向的,第16讲四闸前后端都要落。
  4. 把 marketplace 当摆设
    。双轨只开源不收费,或只收费不开源,都没吃到《OPC 落地手册》的护城河。对策:底座开源做信任,模板上架做收入,二者都动。
  5. 不读 *.test.ts 当真相
    。canvas/core 下每个模块都有 .test.ts(如 graphExec.test.ts),那是作者给自己定的"契约测试"。对策:读源码先读测试,比读文档快三倍。
  6. 直接跑生产库不备
    。忘了 lifespan 里的 backup.snapshot_if_stale。对策:上线前先确认备份循环在跑,数据不丢优先于功能炫。
  7. 忽略 lifespan 自举
    。以为 ensure_admin 可有可无,结果运营后台登不进。对策:自举是幂等的,照抄即可,别删。
  8. 把"示意"当"真实接口"
    。第15讲 opc_executor_sketch.py 标了"非逐行真实源码",有人却拿它当 OPC 内部 API 调。对策:凡标"示意"的,落地前回真实仓库核对。
  9. 不装依赖直接 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 讲——从造机器人,到开公司,再到合法、持续收钱。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料