ctos-architecture

name	ctos-architecture
description	CTOS（ching-tech-os）架構導覽與改動定位指南。當使用者要在 ching-tech-os 加新功能、新前端 App、新後端內建模組、extends 外部模組，或新增 CTOS AI Skill 時使用。提供「改哪一層」決策樹、內建 App 逐檔 checklist、contributes.yaml 四種貢獻規格，以及 CTOS AI Skill 與 Claude Code skill 的區分。

CTOS 架構與功能擴充指南

CTOS 是 FastAPI + PostgreSQL（asyncpg + Alembic）+ 原生 JS（IIFE，無框架）的內部平台。 加功能前先用下面的決策樹定位「要動哪一層」，再照對應 checklist 逐檔處理。 本 skill 只給骨架；細節以 repo 內文件為準，動手前先讀「必讀文件」一節列的檔案。

1. 決策樹：功能該放哪一層

這個需求是？
├─ 修改/擴充既有功能（加欄位、加端點、改 UI）
│   → 直接改既有模組。先查 docs/module-index.md 的
│     「常見修改場景速查」定位檔案，不要新開模組。
│
├─ 全新的平台功能，所有部署都該有（如知識庫、分享管理這類）
│   → 內建新 App：在 backend/src/ching_tech_os/modules.py 的
│     BUILTIN_MODULES 加 entry。見第 2 節 checklist。
│
├─ 需要獨立授權 / 獨立版控 / 客戶特定（如 his、law、erpnext）
│   → extends 外部模組：git submodule + contributes.yaml 宣告，
│     不修改主系統任何程式碼。見第 3 節。
│
└─ 要給 CTOS 的 AI（Bot / AI 助手）新能力（prompt + 工具 + 可選前端 App）
    → CTOS AI Skill：SKILL.md（frontmatter 含 metadata.ctos /
      contributes），由 SkillManager 掃描載入。見第 4 節。

判斷補充：

• 模組啟停由 .env 的 ENABLED_MODULES 控制（* 全開，或逗號分隔清單；core 永遠啟用）。modules.py 的 is_module_enabled() 是判斷點。
• extends 模組裡的工具有三種提供方式（in-process mcp_tools / 外部 mcp_servers / Skill Script），選擇矩陣在 docs/extends-module.md 的「三種工具提供方式的選擇」表格，別憑感覺選。

2. 內建新 App 逐檔 checklist

2.1 後端

• backend/src/ching_tech_os/modules.py：在 BUILTIN_MODULES 加 entry。欄位依 ModuleInfo TypedDict：
  • id（必填，模組 ID，同時是 ENABLED_MODULES 的 key）
  • source: "builtin"（必填）