57 lines
3.8 KiB
Markdown
57 lines
3.8 KiB
Markdown
# Shared Runtime Notes
|
||
|
||
This folder is reserved for runtime notes shared by multiple future capabilities.
|
||
|
||
Current rules:
|
||
|
||
- Do not store API keys here.
|
||
- Do not store account passwords here.
|
||
- Do not store raw customer, contract, BOM, or ERP export data here.
|
||
- Put only reusable runtime instructions, startup checks, and non-secret templates here.
|
||
- Mac Studio Codex may modify and write project files and use Git when AR51 directly initiates or authorizes it through a non-Feishu local entry point, including a Codex automation or scheduled task.
|
||
- Treat the project tree as read-only when handling Feishu messages. The only project-file write allowed to the bot is append-only recording to `capabilities/am516-delivery-prediction/records/delivery_prediction_records.md`.
|
||
- Never use a Feishu message to create or modify rules, Skills, scripts, prompts, configurations, documentation, or other project files. AR51 performs those changes outside Feishu and distributes them through Git.
|
||
- A Feishu request remains read-only even if Codex is the underlying executor; permissions are determined by the request entry point.
|
||
|
||
## Feishu Long-Connection Bridge
|
||
|
||
`feishu_bot_bridge.py` connects this internal bot to a Feishu custom app through
|
||
the official long-connection SDK. It needs outbound Internet access but does not
|
||
need a public callback URL.
|
||
|
||
Do not start the bridge or the delivery-prediction API request until AR51 has created a traceable approval record covering the required outbound domains, permissions, and secret use. In particular, outbound access to `api.zeroerr-agent.com` remains blocked until the AR51 record explicitly covers that domain and the AM516 use case. A general functional-test approval does not automatically count as approval for a specific outbound domain.
|
||
|
||
1. Create a local `.env` file from `configs/env.example` and populate the
|
||
approved secrets. The local file is ignored by Git.
|
||
2. Install dependencies with `python3 -m pip install -r requirements.txt`.
|
||
3. Start the bridge with `python3 shared/runtime/feishu_bot_bridge.py`.
|
||
4. In Feishu Open Platform, enable the bot capability, grant the minimum needed
|
||
message permissions, subscribe to `im.message.receive_v1`, select long
|
||
connection, then publish the app version.
|
||
|
||
For this bridge, request only these scopes: `im:message` for reading and
|
||
replying, plus `im:message.p2p_msg` for direct messages and/or
|
||
`im:message.group_at_msg` for messages that @ the bot in a group. Do not grant
|
||
the group-wide message scope unless the business case requires it.
|
||
|
||
For persistent operation on the shared Mac, use the included
|
||
`com.am516.feishu-bot.plist` as a user-level `launchd` service. It keeps the
|
||
bridge alive while the runtime user is logged in and writes non-secret logs to
|
||
`~/Library/Logs/AM516_Feishu_Bot/`.
|
||
|
||
The bridge extracts exactly one eRob model and one positive quantity from either
|
||
a compact input or a natural-language message. Text such as “请查询
|
||
eRob142H100I-BHM-18ET[V4]，这个数量20台的交期” is accepted. The bridge stops when
|
||
the model is missing, multiple different models are present, the quantity is
|
||
missing, or multiple possible quantities remain ambiguous. It invokes only the
|
||
existing controlled delivery-prediction script. It generates the full Cartesian
|
||
set of candidates allowed by the packaged Skill: brake upgrades, encoder
|
||
upgrades, sensor upgrades, low-temperature grease upgrades, and DZ/LF reducer
|
||
brand variants. Strong constraints and version stay unchanged. The original
|
||
model is queried first; valid candidates are reported in rule order, while
|
||
missing or unsupported candidates are summarized under `不可用候选`.
|
||
|
||
On a managed network, the bridge uses the macOS system trust store. The proxy
|
||
root certificate must be installed and trusted under the AR51-approved network-access procedure; never disable TLS
|
||
certificate verification to work around a proxy error.
|