foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/api/routes/ahs.py

@@ -1,12 +1,12 @@
 """AHS 执行链:技能安装/管理、MCP 接入、Markdown 指令技能、策略封杀、运行、断路器、钩子审计。
 
-从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api.current_os()`
 晚绑定读取;路由用 `@app` 装饰器在 import 时注册。
 """
 
 import asyncio
 import uuid
-from typing import Optional
+from typing import Optional, cast
 
 from fastapi import HTTPException
 from pydantic import BaseModel
@@ -15,24 +15,18 @@ import foxclaw.api as _api
 from .. import app
 
 
-# ============ AHS 执行链(Agent Harness Skills 标准)============
-
 class AHSRunPayload(BaseModel):
     task: str
     confirmed: bool = False
-    # 【P2-2】断点续跑:传上次响应里的 pending_confirmation(确认后连 confirmed=True 一起传)。
-    # Optional:pydantic v2 下 dict=None 字段收到显式 null 会 422,必须 Optional。
     resume_state: Optional[dict] = None
-    # 【P1】关键操作(send/pay/destructive)二次确认码:上次响应 pending_confirmation.confirm_nonce。
-    # 单次使用、绑定 skill+参数、默认 5 分钟过期。也可直接放在 resume_state 里,二者等价。
     confirm_nonce: str = ""
 
 
 @app.get("/api/ahs/skills")
 async def ahs_list_skills():
     """列出注册的 skill(含信任分级 trust + 封杀标记 blocked)。"""
-    pol = _api._os_instance.skill_policy
-    out = _api._os_instance.skill_registry.catalog()
+    pol = _api.os_instance().skill_policy
+    out = _api.os_instance().skill_registry.catalog()
     for s in out:
         s["blocked"] = pol.is_blocked(s.get("id", ""))
     return {"skills": out}
@@ -45,22 +39,22 @@ class PolicyDenyPayload(BaseModel):
 @app.get("/api/ahs/policy")
 async def ahs_policy_get():
     """全局封杀策略快照(deny/allow)。"""
-    return _api._os_instance.skill_policy.snapshot()
+    return _api.os_instance().skill_policy.snapshot()
 
 
 @app.post("/api/ahs/policy/deny")
 async def ahs_policy_deny(p: PolicyDenyPayload):
     """封杀一个技能 id(deny 压倒 enable,立即对所有执行/注入生效)。"""
-    _api._os_instance.skill_policy.deny(p.id)
-    return {"ok": True, "policy": _api._os_instance.skill_policy.snapshot()}
+    _api.os_instance().skill_policy.deny(p.id)
+    return {"ok": True, "policy": _api.os_instance().skill_policy.snapshot()}
 
 
 @app.delete("/api/ahs/policy/deny/{skill_id}")
 async def ahs_policy_undeny(skill_id: str):
     """解封。E1:被 policy 层(管理员 FOXCLAW_POLICY_DENY / policy.json)锁定的技能运行时无法解封,
     诚实返回 ok=False + 原因(不再假报成功);其余情况与改前一致(ok=True)。"""
-    _api._os_instance.skill_policy.undeny(skill_id)
-    snap = _api._os_instance.skill_policy.snapshot()
+    _api.os_instance().skill_policy.undeny(skill_id)
+    snap = _api.os_instance().skill_policy.snapshot()
     if skill_id in snap.get("policy_deny", []):
         return {"ok": False,
                 "reason": f"「{skill_id}」被管理员策略(policy 层)锁定,运行时无法解封", "policy": snap}
@@ -71,23 +65,21 @@ class SkillInstallPayload(BaseModel):
     id: str
     name: str
     description: str = ""
-    kind: str                                  # 只允许 "web_api" | "mcp"
+    kind: str
     triggers: list = []
-    side_effect: str = "write"                 # read/write/send/pay;不传按有副作用(会要求确认)
+    side_effect: str = "write"
     destructive: bool = False
     external: bool = True
     params: dict = {}
-    # web_api
     endpoint: str = ""
     http_method: str = "GET"
     http_headers: dict = {}
     param_location: str = "auto"
     allow_local: bool = False
     timeout: float = 10.0
-    # mcp
     mcp_server: str = ""
     mcp_tool: str = ""
-    acknowledged: bool = False                 # warn 级风险,用户确认后置 true
+    acknowledged: bool = False
 
 
 class SkillPatchPayload(BaseModel):
@@ -98,9 +90,6 @@ class SkillTestPayload(BaseModel):
     args: dict = {}
     confirmed: bool = False
     mode: str = "strict"
-    # 关键操作(send/pay/destructive)的二次确认码:上次响应里的 confirm_nonce。
-    # 宿主注入了 confirms(见 foxclaw/__init__.py)时,confirmed=True 只有配有效 nonce
-    # 才放行 —— 原先这个端点收不到 nonce,界面上点「确认」永远退回 needs_confirmation。
     confirm_nonce: str = ""
 
 
@@ -124,66 +113,66 @@ def _validate_install(p: "SkillInstallPayload"):
 async def ahs_install_skill(p: SkillInstallPayload):
     """安装/注册一个 web_api|mcp 技能(过安装审核门 + 持久化)。同 id 覆盖更新。"""
     _validate_install(p)
-    from foxclaw.skills import SkillSpec
+    from foxclaw.skills import SideEffect, SkillKind, SkillSpec
     from foxclaw.skills.review import review_install
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     _existing = reg.get(p.id)
     if _existing is not None and _existing.source == "builtin":
         raise HTTPException(409, "该 id 属于内置技能,不能覆盖")
     existed = _existing is not None
     spec = SkillSpec(
-        id=p.id, name=p.name, description=p.description, kind=p.kind,
-        triggers=list(p.triggers), side_effect=p.side_effect,
+        id=p.id, name=p.name, description=p.description,
+        kind=cast(SkillKind, p.kind), triggers=list(p.triggers),
+        side_effect=cast(SideEffect, p.side_effect),
         destructive=p.destructive, external=p.external, params=dict(p.params),
         endpoint=p.endpoint, http_method=p.http_method, http_headers=dict(p.http_headers),
         param_location=p.param_location, allow_local=p.allow_local, timeout=p.timeout,
         mcp_server=p.mcp_server, mcp_tool=p.mcp_tool, source="user",
     )
-    verdict = review_install(spec)                       # 安装审核门
+    verdict = review_install(spec)
     if verdict["verdict"] == "deny":
         raise HTTPException(403, detail={"error": "install_denied", "reasons": verdict["reasons"]})
     if verdict["verdict"] == "warn" and not p.acknowledged:
         raise HTTPException(409, detail={"needs_ack": True, "warnings": verdict["warnings"]})
     reg.register(spec)
-    _api._os_instance.skill_store.save(reg)
+    _api.os_instance().skill_store.save(reg)
     return {"ok": True, "skill": spec.to_dict(), "created": not existed, "warnings": verdict["warnings"]}
 
 
 @app.patch("/api/ahs/skills/{skill_id}")
 async def ahs_patch_skill(skill_id: str, p: SkillPatchPayload):
     """启停一个技能(内置/用户均可,持久化)。"""
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     sp = reg.get(skill_id)
     if sp is None:
         raise HTTPException(404, "技能不存在")
     sp.enabled = bool(p.enabled)
-    _api._os_instance.skill_store.save(reg)
+    _api.os_instance().skill_store.save(reg)
     return {"ok": True, "skill": sp.to_dict()}
 
 
 @app.delete("/api/ahs/skills/{skill_id}")
 async def ahs_delete_skill(skill_id: str):
     """删除用户安装的技能;内置技能不可删(只能停用)。"""
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     sp = reg.get(skill_id)
     if sp is None:
         raise HTTPException(404, "技能不存在")
     if sp.source == "builtin":
         raise HTTPException(409, "内置技能不可删除,只能停用")
     reg.unregister(skill_id)
-    _api._os_instance.skill_store.save(reg)
+    _api.os_instance().skill_store.save(reg)
     return {"ok": True}
 
 
 @app.post("/api/ahs/skills/{skill_id}/test")
 async def ahs_test_skill(skill_id: str, p: SkillTestPayload):
     """单技能测试调用:走真实权限管线/断路器/SSRF。副作用未确认 → needs_confirmation。"""
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     sp = reg.get(skill_id)
     if sp is None:
         raise HTTPException(404, "技能不存在")
-    # 阻塞 I/O(web_api httpx / mcp 桥,最长数十秒)放线程池,勿堵死事件循环(否则慢工具冻全站)
-    res = await asyncio.to_thread(_api._os_instance.skill_adapter.invoke,
+    res = await asyncio.to_thread(_api.os_instance().skill_adapter.invoke,
                                   sp, p.args, p.confirmed, p.mode,
                                   confirm_nonce=p.confirm_nonce)
     return res.to_dict()
@@ -194,7 +183,7 @@ class McpServerPayload(BaseModel):
     name: str = ""
     url: str
     headers: dict = {}
-    transport: str = "streamable_http"     # streamable_http | sse
+    transport: str = "streamable_http"
     acknowledged: bool = False
 
 
@@ -214,22 +203,21 @@ async def mcp_add_server(p: McpServerPayload):
         raise HTTPException(409, detail={"needs_ack": True, "warnings": verdict["warnings"]})
     cfg = {"id": p.id, "name": p.name or p.id, "url": p.url,
            "headers": dict(p.headers), "transport": p.transport}
-    sentinel = getattr(_api._os_instance, "sentinel", None)
+    sentinel = getattr(_api.current_os(), "sentinel", None)
     try:
         if sentinel is not None:
-            # 守门人模式:headers 只在这次调用经手,发现由守门人代执行,主进程只存元数据。
-            tools = await asyncio.to_thread(_api._os_instance.mcp_add_server_guardian, cfg)
+            tools = await asyncio.to_thread(_api.os_instance().mcp_add_server_guardian, cfg)
         else:
-            tools = await asyncio.to_thread(_api._os_instance.mcp_manager.add_server, cfg)  # 桥阻塞→线程池
-            _api._os_instance.mcp_store.save(_api._os_instance.mcp_manager.servers())
+            tools = await asyncio.to_thread(_api.os_instance().mcp_manager.add_server, cfg)
+            _api.os_instance().mcp_store.save(_api.os_instance().mcp_manager.servers())
     except Exception as e:
         raise HTTPException(502, f"连接 MCP server 失败: {e}")
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     n = 0
     for tool in tools:
         reg.register(tool_to_spec(p.id, tool)); n += 1
-    _api._os_instance.skill_store.save(reg)
-    _api._os_instance.sync_mcp_servers_to_sentinel()   # 元数据同步;守门人已持有 headers
+    _api.os_instance().skill_store.save(reg)
+    _api.os_instance().sync_mcp_servers_to_sentinel()
     return {"ok": True, "server": {k: cfg[k] for k in ("id", "name", "url", "transport")},
             "tools_registered": n, "warnings": verdict["warnings"]}
 
@@ -237,10 +225,10 @@ async def mcp_add_server(p: McpServerPayload):
 @app.get("/api/ahs/mcp/servers")
 async def mcp_list_servers():
     """列出已接入 MCP server(工具数由注册表派生,无需连接)。"""
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     all_sk = reg.all_including_disabled()
     out = []
-    for c in _api._os_instance.mcp_manager.servers():
+    for c in _api.os_instance().mcp_manager.servers():
         tc = sum(1 for s in all_sk if s.kind == "mcp" and s.mcp_server == c["id"])
         out.append({"id": c["id"], "name": c["name"], "url": c["url"],
                     "transport": c["transport"], "tool_count": tc})
@@ -250,17 +238,17 @@ async def mcp_list_servers():
 @app.delete("/api/ahs/mcp/servers/{server_id}")
 async def mcp_remove_server(server_id: str):
     """移除 server + 其注册的所有 mcp 技能。"""
-    mgr = _api._os_instance.mcp_manager
+    mgr = _api.os_instance().mcp_manager
     if not mgr.remove_server(server_id):
         raise HTTPException(404, "server 不存在")
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     removed = [s.id for s in reg.all_including_disabled()
                if s.kind == "mcp" and s.mcp_server == server_id]
     for sid in removed:
         reg.unregister(sid)
-    _api._os_instance.skill_store.save(reg)
-    _api._os_instance.mcp_store.save(mgr.servers())
-    _api._os_instance.sync_mcp_servers_to_sentinel()   # 配置(含凭证)同步给守门人
+    _api.os_instance().skill_store.save(reg)
+    _api.os_instance().mcp_store.save(mgr.servers())
+    _api.os_instance().sync_mcp_servers_to_sentinel()
     return {"ok": True, "removed_skills": len(removed)}
 
 
@@ -268,38 +256,38 @@ async def mcp_remove_server(server_id: str):
 async def mcp_refresh_server(server_id: str):
     """重连拉工具:新增/更新技能,删除已消失的工具技能。"""
     from foxclaw.skills.mcp_client import tool_to_spec
-    mgr = _api._os_instance.mcp_manager
+    mgr = _api.os_instance().mcp_manager
     if not any(s["id"] == server_id for s in mgr.servers()):
         raise HTTPException(404, "server 不存在")
-    sentinel = getattr(_api._os_instance, "sentinel", None)
+    sentinel = getattr(_api.current_os(), "sentinel", None)
     try:
         if sentinel is not None:
-            tools = await asyncio.to_thread(sentinel.mcp_list_tools, server_id)  # 守门人代发现(失败抛异常)
+            tools = await asyncio.to_thread(sentinel.mcp_list_tools, server_id)
         else:
-            tools = await asyncio.to_thread(mgr.list_tools, server_id)  # 桥阻塞→线程池
+            tools = await asyncio.to_thread(mgr.list_tools, server_id)
     except Exception as e:
         raise HTTPException(502, f"刷新失败: {e}")
-    reg = _api._os_instance.skill_registry
+    reg = _api.os_instance().skill_registry
     fresh = set()
     for tool in tools:
         spec = tool_to_spec(server_id, tool); reg.register(spec); fresh.add(spec.id)
     for s in [s for s in reg.all_including_disabled()
               if s.kind == "mcp" and s.mcp_server == server_id and s.id not in fresh]:
         reg.unregister(s.id)
-    _api._os_instance.skill_store.save(reg)
+    _api.os_instance().skill_store.save(reg)
     return {"ok": True, "tools": len(fresh)}
 
 
 class MdSkillPayload(BaseModel):
     content: str = ""
-    package_b64: str = ""            # OpenClaw 包(zip)的 base64;有则优先,解包取 SKILL.md
+    package_b64: str = ""
     id: str = ""
     acknowledged: bool = False
 
 
 class MdSkillPatchPayload(BaseModel):
     enabled: bool | None = None
-    triggers: list | None = None            # 改触发词(免解压重打包);None=不动
+    triggers: list | None = None
 
 
 @app.post("/api/ahs/md-skills")
@@ -326,17 +314,17 @@ async def md_install(p: MdSkillPayload):
     if not p.acknowledged:
         raise HTTPException(409, detail={"needs_ack": True, "warnings": [
             "此技能会把内容注入你 AI 的提示词、影响其行为,仅从可信来源安装"]})
-    reg = _api._os_instance.md_skills
+    reg = _api.os_instance().md_skills
     existed = reg.get(skill.id) is not None
     reg.register(skill)
-    _api._os_instance.md_store.save(reg)
+    _api.os_instance().md_store.save(reg)
     return {"ok": True, "skill": skill.to_meta(), "created": not existed}
 
 
 @app.get("/api/ahs/md-skills")
 async def md_list():
-    pol = _api._os_instance.skill_policy
-    out = _api._os_instance.md_skills.catalog()
+    pol = _api.os_instance().skill_policy
+    out = _api.os_instance().md_skills.catalog()
     for s in out:
         s["blocked"] = pol.is_blocked(s.get("id", ""))
     return {"skills": out}
@@ -344,7 +332,7 @@ async def md_list():
 
 @app.get("/api/ahs/md-skills/{skill_id}")
 async def md_get(skill_id: str):
-    s = _api._os_instance.md_skills.get(skill_id)
+    s = _api.os_instance().md_skills.get(skill_id)
     if s is None:
         raise HTTPException(404, "指令技能不存在")
     return s.to_dict()
@@ -352,7 +340,7 @@ async def md_get(skill_id: str):
 
 @app.patch("/api/ahs/md-skills/{skill_id}")
 async def md_patch(skill_id: str, p: MdSkillPatchPayload):
-    reg = _api._os_instance.md_skills
+    reg = _api.os_instance().md_skills
     s = reg.get(skill_id)
     if s is None:
         raise HTTPException(404, "指令技能不存在")
@@ -360,17 +348,17 @@ async def md_patch(skill_id: str, p: MdSkillPatchPayload):
         s.enabled = bool(p.enabled)
     if p.triggers is not None:
         s.triggers = [str(t).strip() for t in p.triggers if str(t).strip()]
-    _api._os_instance.md_store.save(reg)
+    _api.os_instance().md_store.save(reg)
     return {"ok": True, "skill": s.to_meta()}
 
 
 @app.delete("/api/ahs/md-skills/{skill_id}")
 async def md_delete(skill_id: str):
-    reg = _api._os_instance.md_skills
+    reg = _api.os_instance().md_skills
     if reg.get(skill_id) is None:
         raise HTTPException(404, "指令技能不存在")
     reg.unregister(skill_id)
-    _api._os_instance.md_store.save(reg)
+    _api.os_instance().md_store.save(reg)
     return {"ok": True}
 
 
@@ -383,11 +371,10 @@ async def ahs_run(payload: AHSRunPayload):
     【P1】关键操作还需带 confirm_nonce(响应里的 pending_confirmation.confirm_nonce);
     缺/错/过期 → 仍返回 pending_confirmation 并换发新码,不会执行。"""
     from foxclaw.skills import set_loop_session, reset_loop_session
-    # 循环检测按执行链分槽:断点续跑复用同一 task_id,否则每次请求独立(消除跨请求污染)
     sid = (payload.resume_state or {}).get("task_id") or f"ahs_{uuid.uuid4().hex[:8]}"
     token = set_loop_session(sid)
     try:
-        res = await _api._os_instance.ahs_pipeline.run_async(
+        res = await _api.os_instance().ahs_pipeline.run_async(
             payload.task, confirmed=payload.confirmed,
             resume_state=payload.resume_state,
             confirm_nonce=payload.confirm_nonce)
@@ -407,11 +394,11 @@ async def ahs_run(payload: AHSRunPayload):
 @app.get("/api/ahs/breaker")
 async def ahs_breaker_status():
     """断路器状态:各 skill 的失败计数与开闸情况。"""
-    br = _api._os_instance.skill_adapter.breaker
+    br = _api.os_instance().skill_adapter.breaker
     return {"breakers": {sid: br.status(sid) for sid in br._entries}}
 
 
 @app.get("/api/ahs/hooks/audit")
 async def ahs_hooks_audit():
     """钩子审计日志(最近 20 条)。"""
-    return {"audit": _api._os_instance.skill_adapter.hooks.recent_audit(20)}
+    return {"audit": _api.os_instance().skill_adapter.hooks.recent_audit(20)}

package/python/foxclaw/api/routes/attachments.py

@@ -23,11 +23,10 @@ import foxclaw.api as _api
 from .. import app
 
 
-_MAX_ATTACH_BYTES = 20 * 1024 * 1024        # 单附件上限 20MB
-_MAX_TEXT_CHARS = 20000                      # 单文件提取正文上限(防超长文件撑爆上下文)
+_MAX_ATTACH_BYTES = 20 * 1024 * 1024
+_MAX_TEXT_CHARS = 20000
 _ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
 
-# 文本类扩展名 → 直接读正文;.pdf 走 fitz(可选依赖);其余二进制 → 降级为元数据提示
 _TEXT_EXTS = {
     ".txt", ".md", ".markdown", ".csv", ".json", ".yaml", ".yml", ".log",
     ".py", ".js", ".ts", ".html", ".css", ".xml", ".toml", ".ini", ".sh",
@@ -36,7 +35,7 @@ _TEXT_EXTS = {
 
 
 def _att_dir() -> Path:
-    d = Path(_api._os_instance.data_dir) / "attachments"
+    d = Path(_api.os_instance().data_dir) / "attachments"
     d.mkdir(parents=True, exist_ok=True)
     return d
 
@@ -61,7 +60,7 @@ def _extract_text(path: Path, name: str) -> str:
             return ""
     if ext == ".pdf":
         try:
-            import fitz  # PyMuPDF(可选依赖 knowledge-files)
+            import fitz
         except ImportError:
             return ""
         try:
@@ -85,7 +84,7 @@ async def upload_attachment(file: UploadFile = File(...)):
     """通用聊天附件上传:落盘 + 尽力提取正文,返回 {id,name,size,mime,url,text}。
     text 为空表示不可提取(二进制/图片等),前端/LLM 降级为「文件名 + 元数据」提示。"""
     raw_name = (file.filename or "attachment").strip()
-    name = Path(raw_name).name or "attachment"     # 只留 basename,去路径分隔符
+    name = Path(raw_name).name or "attachment"
     data = await file.read()
     if not data:
         raise HTTPException(400, "空文件")

package/python/foxclaw/api/routes/browser.py

@@ -1,6 +1,6 @@
 """浏览器子系统(HIR-Browser)端点。
 
-从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api.current_os()`
 晚绑定读取;路由用 `@app` 装饰器在 import 时注册。
 """
 
@@ -10,30 +10,26 @@ import foxclaw.api as _api
 from .. import app
 
 
-# ── 浏览器子系统(HIR-Browser)：AI 用的浏览器 ─────────────────
-# 感知网页→压缩语义结构→执行动作→校验结果。async 安全(专用工作线程),
-# playwright 缺失时结构化降级(available=False),不崩溃。受 /api 鉴权保护。
-
 class BrowserActPayload(BaseModel):
-    type: str                         # navigate|click|type|scroll|extract|wait
-    target: str | None = None         # 元素编号;navigate 时为 URL
-    value: object | None = None       # type 的文本;scroll 的方向
+    type: str
+    target: str | None = None
+    value: object | None = None
     meta: dict = {}
 
 
 @app.get("/api/browser/status")
 async def browser_status():
     """浏览器子系统能力/会话状态(available/session_active/launch_error)。"""
-    return _api._os_instance.browser_service.status()
+    return _api.os_instance().browser_service.status()
 
 
 @app.get("/api/browser/perceive")
 async def browser_perceive():
     """只感知当前页面语义结构(带编号的可交互元素 + 摘要),不改变页面。"""
-    return await _api._os_instance.browser_service.perceive()
+    return await _api.os_instance().browser_service.perceive()
 
 
 @app.post("/api/browser/act")
 async def browser_act(p: BrowserActPayload):
     """执行一个 Web 动作,返回校验后最新语义结构。"""
-    return await _api._os_instance.browser_service.act(p.model_dump())
+    return await _api.os_instance().browser_service.act(p.model_dump())

package/python/foxclaw/api/routes/domain.py

@@ -1,6 +1,6 @@
 """领域内核端点(B 阶段三内核):财务 / 学习 / 行程 + 多格式文件导入。
 
-从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api.current_os()`
 晚绑定读取;路由用 `@app` 装饰器在 import 时注册。
 """
 
@@ -18,11 +18,9 @@ from foxclaw.core.paths import resolve_import_path
 from .. import app
 
 
-# ── 领域内核端点（B 阶段三内核）─────────────────────────────
-
 class ImportPayload(BaseModel):
     csv_path: Optional[str] = None
-    rows: Optional[list] = None     # 也可直接传记录数组
+    rows: Optional[list] = None
 
 
 def _resolve_csv_path(raw: str) -> str:
@@ -43,7 +41,7 @@ async def finance_analysis(period: Optional[str] = None,
                            current_balance: Optional[float] = None):
     """财务内核综合分析:预算/异常/订阅/烧钱/守门人裁决。"""
     try:
-        return _api._os_instance.finance.analyze_finances(
+        return _api.os_instance().finance.analyze_finances(
             period=period, current_balance=current_balance)
     except Exception as e:
         raise HTTPException(500, f"财务分析失败: {e}")
@@ -52,7 +50,7 @@ async def finance_analysis(period: Optional[str] = None,
 @app.post("/api/finance/import")
 async def finance_import(p: ImportPayload):
     """导入交易数据(CSV 路径或记录数组)。"""
-    rt = _api._os_instance.finance_runtime
+    rt = _api.os_instance().finance_runtime
     src = _resolve_csv_path(p.csv_path) if p.csv_path else ""
     try:
         if src:
@@ -61,7 +59,6 @@ async def finance_import(p: ImportPayload):
             from foxclaw.finance import Transaction
             n = 0
             for row in p.rows:
-                # save=False:整批导完再落盘一次,别在循环里做 N 次磁盘 IO
                 rt.add_transaction(Transaction(**row), run_gatekeeper=False, save=False)
                 n += 1
             if n:
@@ -73,12 +70,10 @@ async def finance_import(p: ImportPayload):
         raise HTTPException(400, f"导入失败: {e}")
 
 
-# ── 自然语言记账(第一线)────────────────────────────────────
-
 class RecordPayload(BaseModel):
     text: str
     account: str = "default"
-    dry_run: bool = False           # 只解析预览,不落账
+    dry_run: bool = False
 
 
 class FxPayload(BaseModel):
@@ -89,7 +84,7 @@ class FxPayload(BaseModel):
 @app.post("/api/finance/record")
 async def finance_record(p: RecordPayload):
     """一句话记账:「今天买了一件衣服花了 105 块」/「明天交房租 3000」。"""
-    rt = _api._os_instance.finance_runtime
+    rt = _api.os_instance().finance_runtime
     try:
         return rt.record_text(p.text, account=p.account, dry_run=p.dry_run)
     except Exception as e:
@@ -99,7 +94,7 @@ async def finance_record(p: RecordPayload):
 @app.get("/api/finance/ledger")
 async def finance_ledger(period: Optional[str] = None):
     """记账本:按月汇总(已发生/计划、按天、按分类、按币种)。"""
-    rt = _api._os_instance.finance_runtime
+    rt = _api.os_instance().finance_runtime
     try:
         return rt.ledger(period)
     except Exception as e:
@@ -109,14 +104,14 @@ async def finance_ledger(period: Optional[str] = None):
 @app.get("/api/finance/fx")
 async def finance_fx():
     """当前汇率表(本位币 CNY)。"""
-    return _api._os_instance.finance_runtime.fx.snapshot()
+    return _api.os_instance().finance_runtime.fx.snapshot()
 
 
 @app.post("/api/finance/fx")
 async def finance_set_fx(p: FxPayload):
     """设置某个币种的记账汇率(比如刷卡当天的实际结算价)。"""
     try:
-        return _api._os_instance.finance_runtime.fx.set_rate(p.currency, p.rate)
+        return _api.os_instance().finance_runtime.fx.set_rate(p.currency, p.rate)
     except ValueError as e:
         raise HTTPException(400, str(e))
 
@@ -125,7 +120,7 @@ async def finance_set_fx(p: FxPayload):
 async def learning_analysis():
     """学习内核综合分析:掌握度/遗忘风险/知识图谱/学习策略。"""
     try:
-        return _api._os_instance.office.analyze_learning()
+        return _api.os_instance().office.analyze_learning()
     except Exception as e:
         raise HTTPException(500, f"学习分析失败: {e}")
 
@@ -134,7 +129,7 @@ async def learning_analysis():
 async def learning_import(p: ImportPayload):
     """导入知识点(办公学习内核)。learn() 内部已把内容存进 HKC(连续 ConceptKU,知识真源),
     不再另做桥接。"""
-    rt = _api._os_instance.learning_runtime
+    rt = _api.os_instance().learning_runtime
     src = _resolve_csv_path(p.csv_path) if p.csv_path else ""
     try:
         if src:
@@ -154,7 +149,7 @@ async def learning_import(p: ImportPayload):
 @app.delete("/api/learning/item/{item_id}")
 async def learning_delete(item_id: str):
     """删除一个学习知识点(内存+复习状态+图谱,并落盘)。"""
-    rt = _api._os_instance.learning_runtime
+    rt = _api.os_instance().learning_runtime
     ok = rt.delete(item_id)
     return {"deleted": ok, "status": rt.status()}
 
@@ -167,7 +162,7 @@ class NotePayload(BaseModel):
 @app.post("/api/learning/note")
 async def learning_note(p: NotePayload):
     """给一个学习知识点追加一条笔记(有内容才存;没新增不写盘)。"""
-    rt = _api._os_instance.learning_runtime
+    rt = _api.os_instance().learning_runtime
     r = rt.add_note(p.item_id, p.note)
     if "error" in r:
         raise HTTPException(400, r["error"])
@@ -178,7 +173,7 @@ async def learning_note(p: NotePayload):
 async def itinerary_plan(mode: str = "driving"):
     """行程内核规划:路线优化/可达性/冲突/守门人 + 高德可视化数据。"""
     try:
-        return _api._os_instance.office.plan_itinerary(mode=mode)
+        return _api.os_instance().office.plan_itinerary(mode=mode)
     except Exception as e:
         raise HTTPException(500, f"行程规划失败: {e}")
 
@@ -186,7 +181,7 @@ async def itinerary_plan(mode: str = "driving"):
 @app.post("/api/itinerary/import")
 async def itinerary_import(p: ImportPayload):
     """导入行程点。"""
-    rt = _api._os_instance.itinerary_runtime
+    rt = _api.os_instance().itinerary_runtime
     src = _resolve_csv_path(p.csv_path) if p.csv_path else ""
     try:
         if src:
@@ -202,9 +197,6 @@ async def itinerary_import(p: ImportPayload):
         raise HTTPException(400, f"导入失败: {e}")
 
 
-# ── 领域导入:超越 csv_path，支持上传 csv / xlsx / json ─────────────────────
-# 三领域运行时的 import_csv 是"列→类型转换"的唯一权威。多格式文件在此统一解析成 rows,
-# 再桥接成运行时认识的临时 CSV → 复用 import_csv 的转换逻辑(不碰运行时,单一真源)。
 _IMPORT_MAX_BYTES = 10 * 1024 * 1024
 _IMPORT_COLUMNS = {
     "finance":   ["amount", "category", "entity", "account", "timestamp", "tags"],
@@ -291,14 +283,14 @@ async def _domain_import_file(domain: str, runtime, file: UploadFile):
 @app.post("/api/finance/import/file")
 async def finance_import_file(file: UploadFile = File(...)):
     """上传 csv/xlsx/json 导入交易。列:amount,category,entity,account,timestamp,tags。"""
-    rt = _api._os_instance.finance_runtime
+    rt = _api.os_instance().finance_runtime
     return await _domain_import_file("finance", rt, file)
 
 
 @app.post("/api/learning/import/file")
 async def learning_import_file(file: UploadFile = File(...)):
     """上传 csv/xlsx/json 导入知识点。列:content,topic,source,tags。"""
-    rt = _api._os_instance.learning_runtime
+    rt = _api.os_instance().learning_runtime
     res = await _domain_import_file("learning", rt, file)
     try:
         rt.build_connections()
@@ -310,5 +302,5 @@ async def learning_import_file(file: UploadFile = File(...)):
 @app.post("/api/itinerary/import/file")
 async def itinerary_import_file(file: UploadFile = File(...)):
     """上传 csv/xlsx/json 导入行程点。列:name,address,lng,lat,start_time,duration_min,city。"""
-    rt = _api._os_instance.itinerary_runtime
+    rt = _api.os_instance().itinerary_runtime
     return await _domain_import_file("itinerary", rt, file)