sophhub 0.4.46 → 0.4.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sophhub",
-  "version": "0.4.46",
+  "version": "0.4.47",
   "description": "SophHub CLI - Manage and download AI Agent skills and agents",
   "type": "module",
   "bin": {

package/skills/sophnet-invoice-assistant/skill.json

@@ -0,0 +1,21 @@
+{
+  "name": "sophnet-invoice-assistant",
+  "version": "1.0.0",
+  "types": [
+    "store"
+  ],
+  "displayName": "Sophnet发票助手",
+  "description": "帮助已登录 Sophnet 的个人用户在 OpenClaw 中收集开票信息、提交发票申请、查询发票状态和下载发票文件。",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-06-26",
+      "changes": [
+        "初始化个人发票助手 skill 骨架",
+        "补充设计文档、脚本入口与参考文档"
+      ]
+    }
+  ],
+  "createdAt": "2026-06-26",
+  "updatedAt": "2026-06-26"
+}

package/skills/sophnet-invoice-assistant/src/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: sophnet-invoice-assistant
+description: Use when an OpenClaw user wants to manage personal Sophnet invoice templates, apply for an invoice, update an invoice application, check invoice status, or download an issued invoice file while already logged in to Sophnet.
+---
+
+# Sophnet Invoice Assistant
+
+用于帮助已登录 Sophnet 的用户完成发票中心相关操作，包括：
+
+- 准备发票上下文
+- 提交发票申请
+- 修改发票申请
+- 查询发票申请状态
+- 下载发票文件
+- 管理发票模板
+
+## Supported actions
+
+- `prepare`
+- `submit`
+- `update`
+- `status`
+- `download`
+- `template_list`
+- `template_save`
+- `template_delete`
+
+## Auth requirements
+
+脚本会按以下优先级自动读取 Sophnet 登录态：
+
+- `SOPHNET_ACCESS_TOKEN`
+- `SOPHNET_COOKIE`
+- `OPENCLAW_JWT_PATH` 指向的 `jwt.json` 中的 `web_jwt`
+- 默认位置的 `jwt.json`
+
+支持的 API Base URL 环境变量：
+
+- `SOPHNET_API_BASE_URL`
+- `SOPHNET_BASE_URL`
+
+## CLI usage
+
+```bash
+cd "<this-skill-directory>"
+uv run {baseDir}/scripts/cli.py --action prepare --user-request "帮我准备发票信息"
+```
+
+```bash
+cd "<this-skill-directory>"
+uv run {baseDir}/scripts/cli.py \
+  --action submit \
+  --user-request "帮我给这两笔充值开票并聚合开一张" \
+  --buyer-type ENTERPRISE \
+  --invoice-type SPECIAL \
+  --title "杭州某某科技有限公司" \
+  --tax-no "9133XXXX" \
+  --address-phone "杭州xx路 0571-xxxx" \
+  --bank-account "招商银行杭州分行 6222xxxx" \
+  --recharge-trans-nos "RCHG001,RCHG002" \
+  --issuing-mode AGGREGATED
+```
+
+```bash
+cd "<this-skill-directory>"
+uv run {baseDir}/scripts/cli.py \
+  --action update \
+  --application-no INV202606250001 \
+  --recharge-trans-nos "RCHG001,RCHG002" \
+  --issuing-mode SEPARATE \
+  --user-request "把这张发票申请改成分开开发票"
+```
+
+## Parameters
+
+- `--action`: `prepare|submit|update|status|download|template_list|template_save|template_delete`
+- `--user-request`: 用户原始请求
+- `--org-id`: 可选，已知个人组织 ID
+- `--application-no`: 可选，查询/下载/修改指定申请时使用
+- `--template-id`: 可选，删除模板时使用
+- `--confirm`: `true|false`
+- `--buyer-type`: `INDIVIDUAL|ENTERPRISE`
+- `--title`: 发票抬头
+- `--tax-no`: 企业税号
+- `--address-phone`: 企业地址电话
+- `--bank-account`: 企业开户行及账号
+- `--invoice-type`: `NORMAL|SPECIAL`
+- `--recharge-trans-nos`: 逗号分隔的充值流水号
+- `--issuing-mode`: `AGGREGATED|SEPARATE`
+- `--save-as-template`: `true|false`
+- `--template-name`: 模板名称
+- `--use-latest-template`: `true|false`
+
+## Current business rules
+
+### Recharge eligibility
+
+- `2026-06-24` 之前的充值记录不支持自助开发票
+- skill 会在 `prepare` 中显式返回：
+  - `AVAILABLE_RECHARGE_RECORDS`
+  - `INELIGIBLE_RECHARGE_RECORDS`
+  - `INVOICE_ELIGIBLE_START_DATE=2026-06-24`
+- 如果用户选择了不可开票记录，`submit` / `update` 会直接失败并提示重新选择
+
+### Multiple recharge records
+
+- 当一次申请关联多条 `rechargeTransNos` 时，必须指定 `issuingMode`
+- 可选值：
+  - `AGGREGATED`: 多条充值记录聚合开票
+  - `SEPARATE`: 每条充值记录分别开票
+- 如果用户选了多条充值记录但没有给出 `issuingMode`，skill 会返回 `STATUS=need_confirmation`
+
+## Current behavior
+
+### `prepare`
+
+- 自动定位当前个人组织
+- 拉取发票模板
+- 拉取可开票充值记录
+- 拉取最近发票申请
+- 额外返回不可开票记录数量与起始日期限制
+
+### `submit`
+
+- 调用真实 Sophnet 发票申请接口
+- 自动解析用户选择的模板、开票信息和充值流水
+- 多条充值流水时要求 `issuingMode`
+- 自动过滤 `2026-06-24` 之前的充值记录
+- 当前默认会将本次开票信息保存为模板
+
+### `update`
+
+- 调用真实 Sophnet 发票申请修改接口
+- 支持修改抬头、税号、地址电话、银行账号、发票类型、充值流水、开票方式
+- 多条充值流水时要求 `issuingMode`
+- 默认先返回确认摘要，再由 OpenClaw 做二次确认
+
+### `status`
+
+- 查询最近申请或指定申请状态
+
+### `download`
+
+- 下载已开具发票的文件信息
+
+### `template_list`
+
+- 查询模板列表，可按模板名称过滤
+
+### `template_save`
+
+- 新增模板或按同名覆盖模板
+
+### `template_delete`
+
+- 按 `templateId` 或 `templateName` 删除模板
+
+## Output format
+
+```text
+STATUS=succeeded|failed|need_confirmation|not_implemented
+ACTION=prepare|submit|update|status|download|template_list|template_save|template_delete
+MESSAGE=...
+```
+
+常见附加字段：
+
+- `ORG_ID`
+- `APPLICATION_NO`
+- `APPLICATION_STATUS`
+- `TITLE`
+- `AMOUNT`
+- `ISSUING_MODE`
+- `TEMPLATE_ID`
+- `TEMPLATE_NAME`
+- `INVOICE_ELIGIBLE_START_DATE`
+- `AVAILABLE_ISSUING_MODES`
+- `INELIGIBLE_RECHARGE_RECORD_COUNT`
+- `ERROR_CODE`
+- `ERROR_MESSAGE`
+
+## Notes
+
+- 当前 skill 面向个人组织发票中心流程
+- 所有操作依赖真实 Sophnet API
+- 不要在输出中打印完整 token、cookie 或其他敏感凭证

package/skills/sophnet-invoice-assistant/src/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "sophnet-invoice-assistant"
+version = "1.0.0"
+description = "Skill-local runtime dependencies for sophnet-invoice-assistant"
+requires-python = ">=3.8"
+dependencies = [
+  "requests>=2.31.0",
+]

package/skills/sophnet-invoice-assistant/src/references/api-contract.md

@@ -0,0 +1,73 @@
+# API Contract Notes
+
+本文档记录 `sophnet-invoice-assistant` 当前对接的 Sophnet 发票中心接口与关键约束。
+
+## Current endpoints
+
+- `GET /orgs/joined-org`
+- `GET /orgs/{orgId}/invoices/templates`
+- `POST /orgs/{orgId}/invoices/templates`
+- `DELETE /orgs/{orgId}/invoices/templates/{templateId}`
+- `GET /orgs/{orgId}/invoices/recharge-records`
+- `POST /orgs/{orgId}/invoices/applications`
+- `PUT /orgs/{orgId}/invoices/applications/{applicationNo}`
+- `GET /orgs/{orgId}/invoices/applications`
+- `GET /orgs/{orgId}/invoices/applications/{applicationNo}/download`
+
+## Request payload notes
+
+创建和修改发票申请都使用以下核心字段：
+
+- `buyerType`
+- `title`
+- `taxNo`
+- `addressPhone`
+- `bankAccount`
+- `invoiceType`
+- `rechargeTransNos`
+- `issuingMode`
+
+模板保存额外使用：
+
+- `saveAsTemplate`
+- `templateName`
+
+## Important business rules
+
+### Multiple recharge records
+
+当 `rechargeTransNos` 数量大于 1 时，后端要求必须传 `issuingMode`：
+
+- `AGGREGATED`
+- `SEPARATE`
+
+后端校验位置：
+
+- `InvoiceApplicationValidator.validateIssuingMode(...)`
+
+### Recharge eligibility start date
+
+`2026-06-24` 之前的充值记录不支持自助开发票。
+
+后端规则常量位置：
+
+- `InvoiceEligibilityRules.ELIGIBLE_RECHARGE_START_DATE`
+- `InvoiceEligibilityRules.ELIGIBLE_RECHARGE_START_DATE_TEXT`
+
+前端同步常量位置：
+
+- `sophnet/web/src/views/organization/invoices/utils.ts`
+  - `INVOICE_ELIGIBLE_START_DATE = "2026-06-24"`
+
+## Suggested client wrappers
+
+- `get_current_personal_org()`
+- `list_invoice_templates(org_id)`
+- `save_invoice_template(org_id, payload)`
+- `delete_invoice_template(org_id, template_id)`
+- `list_invoiceable_recharge_records(org_id, params)`
+- `create_invoice_application(org_id, payload)`
+- `update_invoice_application(org_id, application_no, payload)`
+- `list_invoice_applications(org_id, params)`
+- `get_invoice_application(org_id, application_no)`
+- `download_invoice_file(org_id, application_no)`

package/skills/sophnet-invoice-assistant/src/references/conversation-examples.md

@@ -0,0 +1,16 @@
+# Conversation Examples
+
+## 申请发票
+
+- 用户：帮我开发票
+- Skill：先确认一下，你是要复用上次抬头，还是这次要填新的开票信息？
+
+## 查询状态
+
+- 用户：查一下我的发票进度
+- Skill：我先帮你查最近的发票申请状态。
+
+## 下载发票
+
+- 用户：把已经开的发票发我
+- Skill：我先定位最近已开具的发票记录，如果有多条会让你确认是哪一张。

package/skills/sophnet-invoice-assistant/src/references/error-cases.md

@@ -0,0 +1,16 @@
+# Error Cases
+
+## 登录态缺失
+
+- `AUTH_CONTEXT_MISSING`
+- 提示：当前 Sophnet 登录态缺失，请重新登录后再试。
+
+## 个人组织缺失
+
+- `PERSONAL_ORG_NOT_FOUND`
+- 提示：当前账号下未找到可用的个人组织，暂时无法代你提交发票申请。
+
+## 真实接口未接入
+
+- `API_NOT_IMPLEMENTED`
+- 提示：当前 skill 仅完成骨架搭建，尚未接入真实 Sophnet 发票接口。

package/skills/sophnet-invoice-assistant/src/scripts/__init__.py

@@ -0,0 +1 @@
+"""sophnet-invoice-assistant skill scripts package."""

package/skills/sophnet-invoice-assistant/src/scripts/auth_context.py

@@ -0,0 +1,74 @@
+"""Read Sophnet auth context from runtime environment."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from dto import AuthContext
+
+DEFAULT_JWT_PATHS = (
+    "/home/node/.openclaw/jwt.json",
+    "~/.openclaw/jwt.json",
+)
+
+
+def _normalize_api_base_url(raw_value):
+    value = (raw_value or "").strip()
+    if not value:
+        return "https://www.sophnet.com/api"
+    value = value.rstrip("/")
+    if value.endswith("/api"):
+        return value
+    return value + "/api"
+
+
+def _normalize_access_token(raw_value):
+    value = (raw_value or "").strip()
+    if not value:
+        return None
+    if value.lower().startswith("bearer "):
+        value = value[7:].strip()
+    return value or None
+
+
+def _candidate_jwt_paths():
+    custom_path = (os.environ.get("OPENCLAW_JWT_PATH") or "").strip()
+    if custom_path:
+        yield Path(custom_path).expanduser()
+
+    for raw_path in DEFAULT_JWT_PATHS:
+        yield Path(raw_path).expanduser()
+
+
+def _load_access_token_from_jwt():
+    for path in _candidate_jwt_paths():
+        try:
+            with path.open("r", encoding="utf-8") as fp:
+                payload = json.load(fp)
+        except (OSError, ValueError):
+            continue
+        if not isinstance(payload, dict):
+            continue
+        token = _normalize_access_token(payload.get("web_jwt"))
+        if token:
+            return token
+    return None
+
+
+def _resolve_access_token():
+    explicit_token = _normalize_access_token(os.environ.get("SOPHNET_ACCESS_TOKEN"))
+    if explicit_token:
+        return explicit_token
+    return _load_access_token_from_jwt()
+
+
+def load_auth_context():
+    return AuthContext(
+        api_base_url=_normalize_api_base_url(
+            os.environ.get("SOPHNET_API_BASE_URL") or os.environ.get("SOPHNET_BASE_URL")
+        ),
+        access_token=_resolve_access_token(),
+        cookie=os.environ.get("SOPHNET_COOKIE"),
+    )

package/skills/sophnet-invoice-assistant/src/scripts/cli.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""CLI entry for sophnet-invoice-assistant."""
+
+from __future__ import annotations
+
+import argparse
+
+from auth_context import load_auth_context
+from download_flow import run_download
+from dto import ActionRequest
+from invoice_client import InvoiceClient
+from output import emit_result, failure
+from prepare_flow import run_prepare
+from status_flow import run_status
+from submit_flow import run_submit
+from template_flow import run_template_delete, run_template_list, run_template_save
+from update_flow import run_update
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Sophnet personal invoice assistant skeleton")
+    parser.add_argument(
+        "--action",
+        required=True,
+        choices=["prepare", "submit", "update", "status", "download", "template_list", "template_save", "template_delete"],
+        help="Action to perform",
+    )
+    parser.add_argument(
+        "--user-request",
+        required=True,
+        help="Original user request text",
+    )
+    parser.add_argument(
+        "--org-id",
+        help="Known personal org id",
+    )
+    parser.add_argument(
+        "--application-no",
+        help="Known invoice application number",
+    )
+    parser.add_argument(
+        "--template-id",
+        help="Known invoice template id",
+    )
+    parser.add_argument(
+        "--confirm",
+        default="false",
+        choices=["true", "false"],
+        help="Whether user already confirmed the submit action",
+    )
+    parser.add_argument("--buyer-type", choices=["INDIVIDUAL", "ENTERPRISE"])
+    parser.add_argument("--title")
+    parser.add_argument("--tax-no")
+    parser.add_argument("--address-phone")
+    parser.add_argument("--bank-account")
+    parser.add_argument("--invoice-type", choices=["NORMAL", "SPECIAL"])
+    parser.add_argument(
+        "--recharge-trans-nos",
+        help="Comma-separated recharge transNo list",
+    )
+    parser.add_argument(
+        "--issuing-mode",
+        choices=["AGGREGATED", "SEPARATE"],
+        help="Required when multiple recharge records are selected",
+    )
+    parser.add_argument(
+        "--save-as-template",
+        default="false",
+        choices=["true", "false"],
+    )
+    parser.add_argument("--template-name")
+    parser.add_argument(
+        "--use-latest-template",
+        default="false",
+        choices=["true", "false"],
+    )
+    return parser.parse_args()
+
+
+def build_request(args):
+    return ActionRequest(
+        action=args.action,
+        user_request=args.user_request,
+        org_id=args.org_id,
+        application_no=args.application_no,
+        template_id=args.template_id,
+        confirm=args.confirm == "true",
+        buyer_type=args.buyer_type,
+        title=args.title,
+        tax_no=args.tax_no,
+        address_phone=args.address_phone,
+        bank_account=args.bank_account,
+        invoice_type=args.invoice_type,
+        recharge_trans_nos=args.recharge_trans_nos,
+        issuing_mode=args.issuing_mode,
+        save_as_template=args.save_as_template == "true",
+        template_name=args.template_name,
+        use_latest_template=args.use_latest_template == "true",
+    )
+
+
+def dispatch(request, auth_context, client):
+    if request.action == "prepare":
+        return run_prepare(request, auth_context, client)
+    if request.action == "submit":
+        return run_submit(request, auth_context, client)
+    if request.action == "status":
+        return run_status(request, auth_context, client)
+    if request.action == "download":
+        return run_download(request, auth_context, client)
+    if request.action == "update":
+        return run_update(request, auth_context, client)
+    if request.action == "template_list":
+        return run_template_list(request, auth_context, client)
+    if request.action == "template_save":
+        return run_template_save(request, auth_context, client)
+    if request.action == "template_delete":
+        return run_template_delete(request, auth_context, client)
+    return failure(
+        action=request.action,
+        error_code="UNKNOWN_ACTION",
+        error_message="Unknown action: {0}".format(request.action),
+    )
+
+
+def main():
+    args = parse_args()
+    request = build_request(args)
+    auth_context = load_auth_context()
+    client = InvoiceClient(auth_context)
+    result = dispatch(request, auth_context, client)
+    emit_result(result)
+
+
+if __name__ == "__main__":
+    main()

package/skills/sophnet-invoice-assistant/src/scripts/download_flow.py

@@ -0,0 +1,89 @@
+"""Issued invoice download skeleton."""
+
+from __future__ import annotations
+
+from invoice_client import InvoiceClientError
+from output import build_result, failure, need_confirmation
+
+
+def _candidate_summary(items):
+    values = []
+    for item in items[:5]:
+        values.append(
+            "{0}({1})".format(
+                item.get("applicationNo") or "",
+                item.get("title") or item.get("status") or "unknown",
+            )
+        )
+    return "Multiple issued invoices were found. Specify an application number before downloading: {0}".format(", ".join(values))
+
+
+def run_download(request, auth_context, client):
+    if not auth_context.is_authenticated:
+        return failure(
+            action=request.action,
+            error_code="AUTH_CONTEXT_MISSING",
+            error_message="Current Sophnet auth context is missing. Please log in again.",
+        )
+
+    try:
+        org = client.get_current_personal_org(request.org_id)
+        target_application_no = request.application_no
+        if not target_application_no:
+            page = client.list_invoice_applications(
+                org.get("id"),
+                params={"pageNum": 1, "pageSize": 10, "status": "ISSUED"},
+            )
+            items = page.get("list") or [] if isinstance(page, dict) else []
+            if not items:
+                return failure(
+                    action=request.action,
+                    error_code="NO_ISSUED_APPLICATION_FOUND",
+                    error_message="No issued invoice is currently available for download under the personal org.",
+                    extra={"ORG_ID": str(org.get("id"))},
+                )
+            if len(items) > 1:
+                return need_confirmation(
+                    action=request.action,
+                    summary=_candidate_summary(items),
+                    message="Multiple downloadable invoices were found. Please specify an application number.",
+                    extra={
+                        "ORG_ID": str(org.get("id")),
+                        "CANDIDATE_APPLICATION_NOS": ",".join(
+                            [str(item.get("applicationNo") or "") for item in items[:10]]
+                        ),
+                    },
+                )
+            target_application_no = items[0].get("applicationNo")
+
+        if not target_application_no:
+            return failure(
+                action=request.action,
+                error_code="APPLICATION_NO_REQUIRED",
+                error_message="The invoice application number is required before downloading.",
+            )
+
+        file_info = client.download_invoice_file(org.get("id"), target_application_no)
+    except InvoiceClientError as exc:
+        return failure(
+            action=request.action,
+            error_code=exc.code,
+            error_message=exc.message,
+        )
+
+    return build_result(
+        status="succeeded",
+        action=request.action,
+        message="Invoice download details were retrieved successfully.",
+        extra={
+            "ORG_ID": str(org.get("id")),
+            "ORG_NAME": org.get("name") or "",
+            "APPLICATION_NO": file_info.get("applicationNo") or str(target_application_no),
+            "FILE_NAME": file_info.get("fileName") or "",
+            "CONTENT_TYPE": file_info.get("contentType") or "",
+            "FILE_SIZE": str(file_info.get("fileSize") or ""),
+            "PREVIEW_URL": file_info.get("previewUrl") or "",
+            "DOWNLOAD_URL": file_info.get("downloadUrl") or "",
+            "EXPIRES_IN": str(file_info.get("expiresIn") or ""),
+        },
+    )

package/skills/sophnet-invoice-assistant/src/scripts/dto.py

@@ -0,0 +1,46 @@
+"""Data transfer objects for the invoice assistant skeleton."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+
+@dataclass
+class ActionRequest(object):
+    action: str
+    user_request: str
+    org_id: Optional[str] = None
+    application_no: Optional[str] = None
+    template_id: Optional[str] = None
+    confirm: bool = False
+    buyer_type: Optional[str] = None
+    title: Optional[str] = None
+    tax_no: Optional[str] = None
+    address_phone: Optional[str] = None
+    bank_account: Optional[str] = None
+    invoice_type: Optional[str] = None
+    recharge_trans_nos: Optional[str] = None
+    issuing_mode: Optional[str] = None
+    save_as_template: bool = False
+    template_name: Optional[str] = None
+    use_latest_template: bool = False
+
+
+@dataclass
+class AuthContext(object):
+    api_base_url: str
+    access_token: Optional[str]
+    cookie: Optional[str]
+
+    @property
+    def is_authenticated(self) -> bool:
+        return bool(self.access_token or self.cookie)
+
+
+@dataclass
+class ActionResult(object):
+    status: str
+    action: str
+    message: str
+    extra: Optional[Dict[str, str]] = None