636 lines
38 KiB
PHP
636 lines
38 KiB
PHP
<?php
|
||
declare(strict_types=1);
|
||
|
||
namespace app\mcp\service;
|
||
|
||
/**
|
||
* MCP 工具：少量通用工具覆盖目录里的全部资源，另有几个高频统计的快捷工具；业绩类工具见 PerfTools。
|
||
* 所有工具只读；结果同时给文字摘要 + JSON（很多客户端只把 text 交给模型）。
|
||
*/
|
||
class Tools
|
||
{
|
||
private const READ_ONLY = ['readOnlyHint' => true, 'destructiveHint' => false, 'idempotentHint' => true, 'openWorldHint' => false];
|
||
|
||
/** tools/list */
|
||
public static function definitions(Identity $identity): array
|
||
{
|
||
$tools = [
|
||
self::tool('zyt_whoami', '查看当前绑定的甄养堂账号：姓名、角色、数据范围、可查询的资源数量、今日已用额度。回答“我是谁/我能查什么”或排查无权限时使用。', []),
|
||
self::tool('zyt_catalog', '列出当前账号可以查询的甄养堂数据资源（按业务分组）。先用它找到资源标识 resource，再用 zyt_describe 看参数，用 zyt_query / zyt_get / zyt_count 查询。', [
|
||
'domain' => ['type' => 'string', 'description' => '只看某个业务分组，如“诊单与处方”“订单与收款”'],
|
||
'keyword' => ['type' => 'string', 'description' => '按名称或标识过滤，如“处方”“排班”“订单”'],
|
||
'include_closed' => ['type' => 'boolean', 'description' => '同时列出暂未开放的资源及原因'],
|
||
]),
|
||
self::tool('zyt_describe', '查看某个数据资源的说明：可用查询参数及含义、类型（列表/详情/统计）、口径说明。', [
|
||
'resource' => ['type' => 'string', 'description' => '资源标识，来自 zyt_catalog，如 doctor.appointment/lists'],
|
||
], ['resource']),
|
||
self::tool('zyt_query', '查询列表或统计类资源，结果与该账号在甄养堂后台看到的一致（按其权限和数据范围）。翻页一律用外层 page/page_size（列表默认每页 20 条、最多 50 条；自带分页的统计明细最多 100 条），结果里有 total 和 has_more（统计明细在 result.paging）。', [
|
||
'resource' => ['type' => 'string', 'description' => '资源标识，如 tcm.diagnosis/lists'],
|
||
'params' => ['type' => 'object', 'description' => '查询参数，名称见 zyt_describe；日期用 YYYY-MM-DD', 'additionalProperties' => true],
|
||
'page' => ['type' => 'integer', 'minimum' => 1, 'description' => '页码，从 1 开始'],
|
||
'page_size' => ['type' => 'integer', 'minimum' => 1, 'maximum' => McpConfig::maxPageSize(), 'description' => '每页条数'],
|
||
'fields' => ['type' => 'array', 'items' => ['type' => 'string'], 'description' => '只返回这些字段（可选，减少篇幅）'],
|
||
], ['resource']),
|
||
self::tool('zyt_get', '查询详情类资源的一条记录（如某个诊单、处方、订单的详情）。会校验这条记录是否在当前账号的数据范围内。', [
|
||
'resource' => ['type' => 'string', 'description' => '详情类资源标识，如 tcm.diagnosis/readonlyDetail'],
|
||
'id' => ['type' => 'string', 'description' => '记录 ID（数字写成字符串也可以）'],
|
||
'params' => ['type' => 'object', 'description' => '其他参数（可选）', 'additionalProperties' => true],
|
||
], ['resource', 'id']),
|
||
self::tool('zyt_count', '只统计某个列表资源在给定条件下的总条数（不返回明细），适合“有多少”“几个”类问题。', [
|
||
'resource' => ['type' => 'string', 'description' => '列表类资源标识'],
|
||
'params' => ['type' => 'object', 'description' => '查询参数', 'additionalProperties' => true],
|
||
], ['resource']),
|
||
self::tool('zyt_file', '读取某条记录里的附件（舌象照片、检查报告等图片或 PDF）。结果里显示“[附件×N…]”时用它读取第 index 个附件。', [
|
||
'resource' => ['type' => 'string', 'description' => '附件所在的详情或列表资源标识'],
|
||
'id' => ['type' => 'string', 'description' => '记录 ID（数字写成字符串也可以）'],
|
||
'field' => ['type' => 'string', 'description' => '附件字段名，如 tongue_images'],
|
||
'index' => ['type' => 'integer', 'minimum' => 0, 'description' => '第几个附件，从 0 开始'],
|
||
], ['resource', 'id', 'field']),
|
||
];
|
||
foreach (self::presets() as $name => $preset) {
|
||
$resource = Catalog::get($preset['resource']);
|
||
if ($resource && Catalog::denialFor($identity, $resource) === null) {
|
||
$tools[] = self::tool($name, $preset['description'], $preset['args'], $preset['required']);
|
||
}
|
||
}
|
||
return array_merge($tools, PerfTools::definitions($identity));
|
||
}
|
||
|
||
/** tools/call，返回 CallToolResult */
|
||
public static function call(Identity $identity, string $name, array $args, array $context): array
|
||
{
|
||
$started = microtime(true);
|
||
$audit = ['grant_id' => $identity->grant['id'] ?? 0, 'admin_id' => $identity->adminId, 'tool' => $name,
|
||
'arguments' => $args, 'client_task_id' => $context['task_id'] ?? '', 'ip' => $context['ip'] ?? ''];
|
||
try {
|
||
$presets = self::presets();
|
||
$result = match (true) {
|
||
$name === 'zyt_whoami' => self::whoami($identity),
|
||
$name === 'zyt_catalog' => self::catalog($identity, $args),
|
||
$name === 'zyt_describe' => self::describe($identity, $args),
|
||
$name === 'zyt_query' => self::query($identity, $args, $audit),
|
||
$name === 'zyt_get' => self::get($identity, $args, $audit),
|
||
$name === 'zyt_count' => self::count($identity, $args, $audit),
|
||
$name === 'zyt_file' => self::file($identity, $args, $audit),
|
||
PerfTools::handles($name) => PerfTools::call($identity, $name, $args, $audit),
|
||
isset($presets[$name]) => self::preset($identity, $presets[$name], $args, $audit),
|
||
default => throw new McpException('没有这个工具：' . $name, 'unknown_tool'),
|
||
};
|
||
$audit['status'] = $audit['status'] ?? 'ok';
|
||
} catch (McpException $e) {
|
||
$audit['status'] = in_array($e->reason, ['denied', 'limited', 'invalid'], true) ? $e->reason : 'error';
|
||
$audit['message'] = $e->getMessage();
|
||
$result = self::error($e->getMessage());
|
||
} catch (\Throwable $e) {
|
||
\think\facade\Log::error('[ai_mcp] 工具执行异常 ' . $name . ': ' . $e->getMessage());
|
||
$audit['status'] = 'error';
|
||
$type = (new \ReflectionClass($e))->getShortName();
|
||
$audit['message'] = '内部错误 ' . $type;
|
||
$result = self::error('查询失败（内部错误 ' . $type . '），请稍后再试；多次出现请联系管理员查看服务器日志');
|
||
}
|
||
$audit['duration_ms'] = (int) round((microtime(true) - $started) * 1000);
|
||
if (!in_array($name, ['zyt_whoami', 'zyt_catalog', 'zyt_describe'], true) || $audit['status'] !== 'ok') {
|
||
AuditLogger::log($audit);
|
||
}
|
||
return $result;
|
||
}
|
||
|
||
private static function whoami(Identity $identity): array
|
||
{
|
||
$open = Catalog::openFor($identity);
|
||
$data = [
|
||
'account' => $identity->publicProfile(),
|
||
'data_scope' => $identity->dataScopeText(),
|
||
'full_phone_visible' => $identity->seesPhone(),
|
||
'full_sensitive_visible' => $identity->seesSensitive(),
|
||
'resources_open' => count($open),
|
||
'rows_today' => RateLimiter::rowsToday($identity->adminId),
|
||
'rows_daily_limit' => McpConfig::dailyRows(),
|
||
'grant_expire_at' => date('Y-m-d H:i', (int) $identity->grant['expire_time']),
|
||
];
|
||
$summary = sprintf('当前账号：%s（%s），数据范围：%s，可查询资源 %d 个。',
|
||
$data['account']['name'], implode('/', $data['account']['roles']) ?: '无角色', $data['data_scope'], $data['resources_open']);
|
||
return self::ok($summary, $data);
|
||
}
|
||
|
||
private static function catalog(Identity $identity, array $args): array
|
||
{
|
||
$domain = trim((string) ($args['domain'] ?? ''));
|
||
$keyword = trim((string) ($args['keyword'] ?? ''));
|
||
$includeClosed = !empty($args['include_closed']);
|
||
$groups = [];
|
||
$closed = [];
|
||
foreach (Catalog::all() as $key => $r) {
|
||
if ($domain !== '' && mb_strpos($r['domain'], $domain) === false) {
|
||
continue;
|
||
}
|
||
if ($keyword !== '' && mb_stripos($r['name'] . ' ' . $key, $keyword) === false) {
|
||
continue;
|
||
}
|
||
$denied = Catalog::denialFor($identity, $r);
|
||
if ($denied === null) {
|
||
$groups[$r['domain']][] = ['resource' => $key, 'name' => $r['name'], 'kind' => self::kindText($r['kind'])];
|
||
} elseif ($includeClosed && $r['status'] !== Catalog::EXCLUDED && ($r['status'] !== Catalog::OPEN || !$r['registered'] || $identity->can($r['perm']))) {
|
||
$closed[] = ['resource' => $key, 'name' => $r['name'], 'reason' => $r['reason'] ?: '无权限'];
|
||
}
|
||
}
|
||
ksort($groups);
|
||
$count = array_sum(array_map('count', $groups));
|
||
$data = ['domains' => $groups, 'total' => $count];
|
||
if ($includeClosed) {
|
||
$data['not_open'] = array_slice($closed, 0, 200);
|
||
}
|
||
return self::ok('可查询的数据资源 ' . $count . ' 个' . ($domain || $keyword ? '（已按条件过滤）' : '') . '。用 zyt_describe 查看参数。', $data);
|
||
}
|
||
|
||
private static function describe(Identity $identity, array $args): array
|
||
{
|
||
$resource = self::resource($identity, (string) ($args['resource'] ?? ''));
|
||
$data = [
|
||
'resource' => $resource['key'],
|
||
'name' => $resource['name'],
|
||
'domain' => $resource['domain'],
|
||
'kind' => self::kindText($resource['kind']),
|
||
'use' => $resource['kind'] === 'detail' ? 'zyt_get' : (in_array($resource['kind'], ['list', 'table'], true) ? 'zyt_query 或 zyt_count' : 'zyt_query'),
|
||
'params' => Catalog::paramDocs($resource),
|
||
'fixed_params' => (array) ($resource['force'] ?? []),
|
||
'note' => (string) ($resource['note'] ?? ''),
|
||
'limits' => ['page_size_max' => McpConfig::maxPageSize(), 'date_range_days_max' => McpConfig::maxRangeDays()],
|
||
];
|
||
if ($resource['kind'] === 'detail') {
|
||
$data['id_param'] = (string) ($resource['guard']['param'] ?? $resource['id_param'] ?? 'id');
|
||
}
|
||
return self::ok('「' . $resource['name'] . '」的查询说明。', $data);
|
||
}
|
||
|
||
private static function query(Identity $identity, array $args, array &$audit): array
|
||
{
|
||
$resource = self::resource($identity, (string) ($args['resource'] ?? ''));
|
||
$audit['resource'] = $resource['key'];
|
||
if ($resource['kind'] === 'detail') {
|
||
throw new McpException('「' . $resource['name'] . '」是详情资源，请用 zyt_get 并提供 id', 'invalid');
|
||
}
|
||
$params = self::params($resource, self::liftPaging($resource, (array) ($args['params'] ?? []), $args));
|
||
if (in_array($resource['kind'], ['list', 'table'], true)) {
|
||
return self::runList($identity, $resource, $params, (int) ($args['page'] ?? 1), (int) ($args['page_size'] ?? McpConfig::defaultPageSize()), (array) ($args['fields'] ?? []), $audit);
|
||
}
|
||
return self::runReport($identity, $resource, self::sinkPaging($resource, $params, $args), $audit);
|
||
}
|
||
|
||
/**
|
||
* 自带分页的统计明细（参数叫 page/page_no 和 page_size，如进线明细、被指派明细）：外层的 page/page_size 放进参数。
|
||
* 以前只看 params，模型照工具说明用外层 page 翻页时每次拿到的都是第一页，看起来像同一批记录反复出现。
|
||
*/
|
||
private static function sinkPaging(array $resource, array $params, array $args): array
|
||
{
|
||
$allowed = array_flip(Catalog::allowedParams($resource));
|
||
$pageKey = isset($allowed['page']) ? 'page' : (isset($allowed['page_no']) ? 'page_no' : null);
|
||
if ($pageKey !== null && !isset($params[$pageKey])) {
|
||
$params[$pageKey] = max(1, (int) ($args['page'] ?? 1));
|
||
}
|
||
if (isset($allowed['page_size']) && !isset($params['page_size'])) {
|
||
$params['page_size'] = max(1, min(100, (int) ($args['page_size'] ?? McpConfig::defaultPageSize())));
|
||
}
|
||
return $params;
|
||
}
|
||
|
||
/** 同一页里 id 相同的行只留一条（后台列表的联表偶尔会把一条记录拆成多行）；有行没有 id 时原样返回 */
|
||
private static function dropDuplicateIds(array $rows): array
|
||
{
|
||
$seen = [];
|
||
$out = [];
|
||
foreach ($rows as $row) {
|
||
if (!is_array($row) || !isset($row['id']) || !is_scalar($row['id'])) {
|
||
return [$rows, 0];
|
||
}
|
||
if (!isset($seen[(string) $row['id']])) {
|
||
$seen[(string) $row['id']] = true;
|
||
$out[] = $row;
|
||
}
|
||
}
|
||
return [$out, count($rows) - count($out)];
|
||
}
|
||
|
||
private static function get(Identity $identity, array $args, array &$audit): array
|
||
{
|
||
$resource = self::resource($identity, (string) ($args['resource'] ?? ''));
|
||
$audit['resource'] = $resource['key'];
|
||
if ($resource['kind'] !== 'detail') {
|
||
throw new McpException('「' . $resource['name'] . '」不是详情资源，请用 zyt_query', 'invalid');
|
||
}
|
||
$id = $args['id'] ?? null;
|
||
if (!is_scalar($id) || (string) $id === '') {
|
||
throw new McpException('请提供记录 id', 'invalid');
|
||
}
|
||
$idParam = (string) ($resource['guard']['param'] ?? $resource['id_param'] ?? 'id');
|
||
$params = self::params($resource, self::liftPaging($resource, (array) ($args['params'] ?? []), $args));
|
||
$params[$idParam] = is_numeric($id) ? (int) $id : (string) $id;
|
||
self::assertQuota($identity, 1);
|
||
$envelope = Dispatcher::call($identity, $resource, $params);
|
||
if ($envelope['code'] !== 1) {
|
||
throw new McpException(self::failText($resource, $envelope), 'denied');
|
||
}
|
||
$policy = FieldPolicy::forIdentity($identity, 20000);
|
||
$record = $policy->apply($envelope['data']);
|
||
RateLimiter::addRows($identity->adminId, 1);
|
||
$audit['result_rows'] = 1;
|
||
$audit['record_ids'] = [(string) $id];
|
||
return self::ok('「' . $resource['name'] . '」ID ' . $id . ' 的详情' . self::maskNote($policy) . '。',
|
||
self::fit(['resource' => $resource['key'], 'id' => $id, 'record' => $record, 'masked' => $policy->maskedFields()]));
|
||
}
|
||
|
||
private static function count(Identity $identity, array $args, array &$audit): array
|
||
{
|
||
$resource = self::resource($identity, (string) ($args['resource'] ?? ''));
|
||
$audit['resource'] = $resource['key'];
|
||
if (!in_array($resource['kind'], ['list', 'table'], true)) {
|
||
throw new McpException('zyt_count 只用于列表资源', 'invalid');
|
||
}
|
||
$params = self::params($resource, self::liftPaging($resource, (array) ($args['params'] ?? []), $args));
|
||
$envelope = Dispatcher::call($identity, $resource, self::listParams($resource, $params, 1, 1));
|
||
if ($envelope['code'] !== 1) {
|
||
throw new McpException(self::failText($resource, $envelope), 'denied');
|
||
}
|
||
$total = (int) ($envelope['data']['count'] ?? 0);
|
||
$policy = FieldPolicy::forIdentity($identity, 2000);
|
||
$data = ['resource' => $resource['key'], 'total' => $total, 'params' => $params];
|
||
if (!empty($envelope['data']['extend'])) {
|
||
$data['extend'] = $policy->apply($envelope['data']['extend']);
|
||
}
|
||
return self::ok('「' . $resource['name'] . '」符合条件的共 ' . $total . ' 条。', $data);
|
||
}
|
||
|
||
private static function file(Identity $identity, array $args, array &$audit): array
|
||
{
|
||
$resource = self::resource($identity, (string) ($args['resource'] ?? ''));
|
||
$audit['resource'] = $resource['key'];
|
||
$id = $args['id'] ?? null;
|
||
$field = (string) ($args['field'] ?? '');
|
||
$index = max(0, (int) ($args['index'] ?? 0));
|
||
if (!is_scalar($id) || $field === '') {
|
||
throw new McpException('请提供 id 和附件字段名 field', 'invalid');
|
||
}
|
||
if ($resource['kind'] === 'detail') {
|
||
$idParam = (string) ($resource['guard']['param'] ?? $resource['id_param'] ?? 'id');
|
||
$envelope = Dispatcher::call($identity, $resource, array_merge([$idParam => $id], (array) ($resource['force'] ?? [])));
|
||
$record = $envelope['code'] === 1 ? (array) $envelope['data'] : [];
|
||
} else {
|
||
$filter = !empty($resource['handler']['table']) ? [] : ['id' => $id];
|
||
$envelope = Dispatcher::call($identity, $resource, self::listParams($resource, $filter, 1, 50));
|
||
$record = [];
|
||
foreach ((array) ($envelope['data']['lists'] ?? []) as $row) {
|
||
if ((string) ($row['id'] ?? '') === (string) $id) {
|
||
$record = $row;
|
||
}
|
||
}
|
||
}
|
||
if ($envelope['code'] !== 1 || $record === []) {
|
||
throw new McpException('找不到这条记录，或它不在当前账号的数据范围内', 'denied');
|
||
}
|
||
$urls = FileFetcher::urls(self::dig($record, $field));
|
||
if (!isset($urls[$index])) {
|
||
throw new McpException('字段 ' . $field . ' 没有第 ' . $index . ' 个附件（共 ' . count($urls) . ' 个）', 'invalid');
|
||
}
|
||
$audit['record_ids'] = [(string) $id];
|
||
$audit['result_rows'] = 1;
|
||
return FileFetcher::content($urls[$index], $resource['name'] . ' #' . $id . ' ' . $field . '[' . $index . ']');
|
||
}
|
||
|
||
private static function preset(Identity $identity, array $preset, array $args, array &$audit): array
|
||
{
|
||
foreach ($preset['required'] as $required) {
|
||
if (!isset($args[$required]) || $args[$required] === '') {
|
||
throw new McpException('缺少参数 ' . $required, 'invalid');
|
||
}
|
||
}
|
||
$resource = self::resource($identity, $preset['resource']);
|
||
$audit['resource'] = $resource['key'];
|
||
$params = self::params($resource, ($preset['map'])($args), true);
|
||
if (($preset['mode'] ?? '') === 'count') {
|
||
$envelope = Dispatcher::call($identity, $resource, self::listParams($resource, $params, 1, 1));
|
||
if ($envelope['code'] !== 1) {
|
||
throw new McpException(self::failText($resource, $envelope), 'denied');
|
||
}
|
||
$policy = FieldPolicy::forIdentity($identity, 2000);
|
||
$data = ['total' => (int) ($envelope['data']['count'] ?? 0), 'extend' => $policy->apply($envelope['data']['extend'] ?? []), 'params' => $params];
|
||
return self::ok($preset['summary'] . '：共 ' . $data['total'] . ' 条。' . ($preset['note'] ?? ''), $data);
|
||
}
|
||
if ($resource['kind'] === 'list') {
|
||
return self::runList($identity, $resource, $params, (int) ($args['page'] ?? 1), (int) ($args['page_size'] ?? McpConfig::defaultPageSize()), [], $audit);
|
||
}
|
||
return self::runReport($identity, $resource, $params, $audit);
|
||
}
|
||
|
||
private static function runList(Identity $identity, array $resource, array $params, int $page, int $size, array $fields, array &$audit): array
|
||
{
|
||
$page = max(1, $page);
|
||
$size = max(1, min(McpConfig::maxPageSize(), $size ?: McpConfig::defaultPageSize()));
|
||
self::assertQuota($identity, $size);
|
||
$envelope = Dispatcher::call($identity, $resource, self::listParams($resource, $params, $page, $size));
|
||
if ($envelope['code'] !== 1) {
|
||
throw new McpException(self::failText($resource, $envelope), 'denied');
|
||
}
|
||
[$rows, $duplicates] = self::dropDuplicateIds(array_values((array) ($envelope['data']['lists'] ?? [])));
|
||
$total = (int) ($envelope['data']['count'] ?? count($rows));
|
||
if (count($rows) > $size) {
|
||
// 个别列表不分页、总是返回全部行：在这里按页切片，避免超出篇幅和每日额度
|
||
$rows = array_slice($rows, ($page - 1) * $size, $size);
|
||
$total = max($total, (int) ($envelope['data']['count'] ?? 0));
|
||
}
|
||
$policy = FieldPolicy::forIdentity($identity, 2000);
|
||
$rows = $policy->apply($rows);
|
||
if ($fields) {
|
||
$keep = array_flip(array_map('strval', $fields));
|
||
$rows = array_map(static fn ($row) => is_array($row) ? array_intersect_key($row, $keep + ['id' => 1]) : $row, $rows);
|
||
}
|
||
RateLimiter::addRows($identity->adminId, count($rows));
|
||
$audit['result_rows'] = count($rows);
|
||
$audit['record_ids'] = AuditLogger::recordIds($rows);
|
||
$data = ['resource' => $resource['key'], 'name' => $resource['name'], 'total' => $total, 'page' => $page, 'page_size' => $size,
|
||
'has_more' => $page * $size < $total, 'rows' => $rows, 'masked' => $policy->maskedFields()];
|
||
if ($duplicates > 0) {
|
||
$data['duplicates_removed'] = $duplicates;
|
||
}
|
||
if (!empty($envelope['data']['extend'])) {
|
||
$data['extend'] = $policy->apply($envelope['data']['extend']);
|
||
}
|
||
if (!empty($resource['note'])) {
|
||
$data['note'] = $resource['note'];
|
||
}
|
||
$data = self::fit($data);
|
||
$summary = sprintf('「%s」共 %d 条，本页第 %d 页 %d 条%s%s%s。', $resource['name'], $total, $page, count($data['rows']),
|
||
$data['has_more'] ? '，还有更多（page=' . ($page + 1) . '）' : '', $duplicates > 0 ? '；后台返回的重复记录 ' . $duplicates . ' 条已去掉' : '', self::maskNote($policy));
|
||
return self::ok($summary, $data);
|
||
}
|
||
|
||
private static function runReport(Identity $identity, array $resource, array $params, array &$audit): array
|
||
{
|
||
self::assertQuota($identity, 1);
|
||
$envelope = Dispatcher::call($identity, $resource, $params);
|
||
if ($envelope['code'] !== 1) {
|
||
throw new McpException(self::failText($resource, $envelope), 'denied');
|
||
}
|
||
$policy = FieldPolicy::forIdentity($identity, 5000);
|
||
$result = $policy->apply($envelope['data']);
|
||
$extra = '';
|
||
$hasLists = is_array($result) && isset($result['lists']) && is_array($result['lists']);
|
||
if ($hasLists) {
|
||
[$result['lists'], $duplicates] = self::dropDuplicateIds(array_values($result['lists']));
|
||
if ($duplicates > 0) {
|
||
$result['duplicates_removed'] = $duplicates;
|
||
$extra .= '；后台返回的重复记录 ' . $duplicates . ' 条已去掉';
|
||
}
|
||
// 自带分页的明细：告诉模型总数和下一页怎么取
|
||
$total = $result['count'] ?? $result['total'] ?? null;
|
||
$pageKey = isset($params['page']) ? 'page' : (isset($params['page_no']) ? 'page_no' : null);
|
||
if (is_numeric($total) && $pageKey !== null && isset($params['page_size'])) {
|
||
$page = (int) $params[$pageKey];
|
||
$hasMore = $page * (int) $params['page_size'] < (int) $total;
|
||
$result['paging'] = ['total' => (int) $total, 'page' => $page, 'page_size' => (int) $params['page_size'], 'has_more' => $hasMore];
|
||
$extra .= sprintf('；共 %d 条，本页第 %d 页 %d 条%s', (int) $total, $page, count($result['lists']), $hasMore ? '，还有更多（page=' . ($page + 1) . '）' : '');
|
||
}
|
||
}
|
||
$rows = $hasLists ? count($result['lists']) : 1;
|
||
RateLimiter::addRows($identity->adminId, $rows);
|
||
$audit['result_rows'] = $rows;
|
||
if ($hasLists) {
|
||
$audit['record_ids'] = AuditLogger::recordIds($result['lists']);
|
||
}
|
||
$data = self::fit(['resource' => $resource['key'], 'name' => $resource['name'], 'params' => $params, 'result' => $result,
|
||
'masked' => $policy->maskedFields(), 'note' => (string) ($resource['note'] ?? '')]);
|
||
return self::ok('「' . $resource['name'] . '」统计结果' . $extra . self::maskNote($policy) . '。', $data);
|
||
}
|
||
|
||
/**
|
||
* 模型常把分页写进 params（如 {"page_size": 50}）：列表资源一律提到外层的 page/page_size；
|
||
* 其他资源若本身不支持这些参数就忽略，避免因为这个白白失败一次。
|
||
*/
|
||
private static function liftPaging(array $resource, array $input, array &$args): array
|
||
{
|
||
$isList = in_array($resource['kind'], ['list', 'table'], true);
|
||
$allowed = array_flip(Catalog::allowedParams($resource));
|
||
$names = ['page' => 'page', 'page_no' => 'page', 'pageNo' => 'page', 'page_size' => 'page_size', 'pageSize' => 'page_size', 'limit' => 'page_size', 'size' => 'page_size'];
|
||
foreach ($names as $name => $target) {
|
||
if (!array_key_exists($name, $input)) {
|
||
continue;
|
||
}
|
||
// 非列表资源自己支持的分页参数（如部分统计接口的 page_no/page_size）、以及列表里名为 limit/size 的真实筛选条件原样保留
|
||
if (isset($allowed[$name]) && (!$isList || in_array($name, ['limit', 'size'], true))) {
|
||
continue;
|
||
}
|
||
if (!isset($args[$target]) && is_numeric($input[$name])) {
|
||
$args[$target] = (int) $input[$name];
|
||
}
|
||
unset($input[$name]);
|
||
}
|
||
return $input;
|
||
}
|
||
|
||
/** 取资源并检查开放状态与权限 */
|
||
public static function resource(Identity $identity, string $key): array
|
||
{
|
||
$resource = Catalog::get(trim($key));
|
||
$denied = Catalog::denialFor($identity, $resource);
|
||
if ($denied !== null) {
|
||
throw new McpException($denied, 'denied');
|
||
}
|
||
return $resource;
|
||
}
|
||
|
||
/** 参数白名单 + 类型清洗 + 日期跨度检查 */
|
||
public static function params(array $resource, array $input, bool $trusted = false): array
|
||
{
|
||
$allowed = array_flip(Catalog::allowedParams($resource));
|
||
$forbidden = array_merge(Catalog::GLOBAL_FORBID, (array) ($resource['forbid'] ?? []));
|
||
$clean = [];
|
||
$rejected = [];
|
||
foreach ($input as $name => $value) {
|
||
$name = (string) $name;
|
||
// 快捷统计工具的参数由代码拼好（trusted），可超出白名单，但仍不能带全局或资源禁用的参数
|
||
if (!isset($allowed[$name]) && !($trusted && !in_array($name, $forbidden, true))) {
|
||
$rejected[] = $name;
|
||
continue;
|
||
}
|
||
if (is_bool($value)) {
|
||
$value = $value ? 1 : 0;
|
||
}
|
||
if (is_array($value)) {
|
||
$value = array_values(array_filter($value, 'is_scalar'));
|
||
$value = array_map(static fn ($v) => is_string($v) ? mb_substr(trim($v), 0, 200) : $v, array_slice($value, 0, 100));
|
||
} elseif (is_string($value)) {
|
||
$value = mb_substr(trim($value), 0, 200);
|
||
} elseif (!is_int($value) && !is_float($value) && $value !== null) {
|
||
continue;
|
||
}
|
||
$clean[$name] = $value;
|
||
}
|
||
if ($rejected) {
|
||
throw new McpException('「' . $resource['name'] . '」不支持参数：' . implode('、', $rejected) . '。可用参数：' . (implode('、', array_keys($allowed)) ?: '无') . '（用 zyt_describe 查看说明）', 'invalid');
|
||
}
|
||
foreach ([['start_date', 'end_date'], ['start_time', 'end_time'], ['create_time_start', 'create_time_end'], ['begin_date', 'end_date']] as [$from, $to]) {
|
||
if (!empty($clean[$from]) && !empty($clean[$to]) && is_string($clean[$from]) && is_string($clean[$to])) {
|
||
$a = strtotime($clean[$from]);
|
||
$b = strtotime($clean[$to]);
|
||
if ($a !== false && $b !== false && ($b - $a) / 86400 > McpConfig::maxRangeDays()) {
|
||
throw new McpException('时间范围超过 ' . McpConfig::maxRangeDays() . ' 天，请缩小范围', 'invalid');
|
||
}
|
||
}
|
||
}
|
||
return array_merge($clean, (array) ($resource['force'] ?? []));
|
||
}
|
||
|
||
public static function listParams(array $resource, array $params, int $page, int $size): array
|
||
{
|
||
return array_merge($params, ['page_no' => $page, 'page_size' => $size, 'page_type' => 1], (array) ($resource['force'] ?? []));
|
||
}
|
||
|
||
public static function assertQuota(Identity $identity, int $rows): void
|
||
{
|
||
if (!RateLimiter::hit('calls_' . $identity->adminId, McpConfig::ratePerMinute(), 60)) {
|
||
throw new McpException('调用太频繁，请稍后再试（每分钟最多 ' . McpConfig::ratePerMinute() . ' 次）', 'limited');
|
||
}
|
||
if (RateLimiter::rowsToday($identity->adminId) + $rows > McpConfig::dailyRows()) {
|
||
throw new McpException('今日通过 AI 查询的数据已达上限（' . McpConfig::dailyRows() . ' 条），如需批量数据请使用后台导出', 'limited');
|
||
}
|
||
}
|
||
|
||
public static function failText(array $resource, array $envelope): string
|
||
{
|
||
$msg = trim($envelope['msg']) ?: '查询失败';
|
||
return '「' . $resource['name'] . '」：' . $msg;
|
||
}
|
||
|
||
private static function maskNote(FieldPolicy $policy): string
|
||
{
|
||
return $policy->maskedFields() ? '（部分个人信息已按权限脱敏：' . implode('、', array_slice($policy->maskedFields(), 0, 8)) . '）' : '';
|
||
}
|
||
|
||
/** 控制返回体积：超出上限时截掉尾部行或长字段 */
|
||
public static function fit(array $data): array
|
||
{
|
||
$limit = McpConfig::maxResponseBytes();
|
||
$size = strlen((string) json_encode($data, JSON_UNESCAPED_UNICODE));
|
||
if ($size <= $limit) {
|
||
return $data;
|
||
}
|
||
if (isset($data['rows']) && is_array($data['rows'])) {
|
||
while ($data['rows'] && strlen((string) json_encode($data, JSON_UNESCAPED_UNICODE)) > $limit) {
|
||
array_pop($data['rows']);
|
||
}
|
||
$data['truncated'] = '内容过长，只返回了前 ' . count($data['rows']) . ' 条；请减小 page_size 或用 fields 指定字段';
|
||
return $data;
|
||
}
|
||
$json = (string) json_encode($data['record'] ?? $data['result'] ?? $data, JSON_UNESCAPED_UNICODE);
|
||
$key = isset($data['record']) ? 'record' : (isset($data['result']) ? 'result' : 'data');
|
||
$data[$key] = mb_strcut($json, 0, $limit - 2000) . '…';
|
||
$data['truncated'] = '内容过长，已截断为文本；请增加筛选条件';
|
||
return $data;
|
||
}
|
||
|
||
private static function dig(array $record, string $field)
|
||
{
|
||
if (array_key_exists($field, $record)) {
|
||
return $record[$field];
|
||
}
|
||
foreach ($record as $value) {
|
||
if (is_array($value)) {
|
||
$found = self::dig($value, $field);
|
||
if ($found !== null) {
|
||
return $found;
|
||
}
|
||
}
|
||
}
|
||
return null;
|
||
}
|
||
|
||
private static function kindText(string $kind): string
|
||
{
|
||
return ['list' => '列表', 'detail' => '详情', 'report' => '统计/查询', 'table' => '数据表', 'other' => '查询'][$kind] ?? '查询';
|
||
}
|
||
|
||
public static function tool(string $name, string $description, array $properties, array $required = []): array
|
||
{
|
||
$schema = ['type' => 'object', 'properties' => $properties ?: new \stdClass(), 'additionalProperties' => false];
|
||
if ($required) {
|
||
$schema['required'] = $required;
|
||
}
|
||
return ['name' => $name, 'description' => $description, 'inputSchema' => $schema, 'annotations' => self::READ_ONLY];
|
||
}
|
||
|
||
private static function ok(string $summary, array $data): array
|
||
{
|
||
return [
|
||
'content' => [['type' => 'text', 'text' => $summary . "\n" . json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)]],
|
||
'structuredContent' => $data ?: new \stdClass(),
|
||
'isError' => false,
|
||
];
|
||
}
|
||
|
||
private static function error(string $message): array
|
||
{
|
||
return ['content' => [['type' => 'text', 'text' => $message]], 'isError' => true];
|
||
}
|
||
|
||
/**
|
||
* 高频统计的快捷工具：固定资源 + 友好参数。只有账号能用对应资源时才出现在工具列表里。
|
||
*/
|
||
private static function presets(): array
|
||
{
|
||
$date = ['type' => 'string', 'description' => '日期 YYYY-MM-DD'];
|
||
return [
|
||
'zyt_stats_appointments' => [
|
||
'resource' => 'doctor.appointment/lists', 'mode' => 'count', 'summary' => '挂号/接诊记录',
|
||
'description' => '统计一段日期内的挂号/接诊数量，并按状态（已预约/已取消/已完成/已过号）分组计数，可按医生筛选。医生账号自动只统计本人，医助只统计自己的患者。',
|
||
'args' => ['start_date' => $date, 'end_date' => $date, 'doctor_id' => ['type' => 'integer', 'description' => '医生ID（可选）'],
|
||
'status' => ['type' => 'integer', 'description' => '只统计某状态：1 已预约、2 已取消、3 已完成、4 已过号（可选）']],
|
||
'required' => ['start_date', 'end_date'],
|
||
'note' => 'extend.status_count 为各状态数量（1 已预约、2 已取消、3 已完成、4 已过号），按预约日期统计。',
|
||
'map' => static fn (array $a) => array_filter(['start_date' => $a['start_date'] ?? null, 'end_date' => $a['end_date'] ?? null,
|
||
'doctor_id' => $a['doctor_id'] ?? null, 'status' => $a['status'] ?? null, 'include_status_counts' => 1], static fn ($v) => $v !== null && $v !== ''),
|
||
],
|
||
'zyt_stats_doctor_workload' => [
|
||
'resource' => 'doctor.statistics/lists', 'summary' => '医生工作量',
|
||
'description' => '按医生统计一段时间的挂号总数、已完成、过号、取消、接诊患者数、成交（开方）数。',
|
||
'args' => ['start_date' => $date, 'end_date' => $date, 'doctor_id' => ['type' => 'integer', 'description' => '只看某位医生（可选）']],
|
||
'required' => ['start_date', 'end_date'],
|
||
'map' => static fn (array $a) => array_filter(['time_type' => 'custom', 'start_date' => $a['start_date'] ?? null, 'end_date' => $a['end_date'] ?? null,
|
||
'doctor_id' => $a['doctor_id'] ?? null], static fn ($v) => $v !== null && $v !== ''),
|
||
],
|
||
'zyt_stats_orders' => [
|
||
'resource' => 'order.order/orderStats', 'summary' => '收款订单统计',
|
||
'description' => '统计截至某日的最近 N 天（1–90）已支付收款订单金额与笔数；order_type：-1 全部已支付、0 退款、1–8 为各费用类型。',
|
||
'args' => ['end_date' => $date, 'days' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 90, 'description' => '最近多少天'],
|
||
'order_type' => ['type' => 'integer', 'description' => '-1 全部已支付（默认）、0 退款、1–8 费用类型']],
|
||
'required' => ['end_date', 'days'],
|
||
'map' => static fn (array $a) => ['end_time' => ($a['end_date'] ?? date('Y-m-d')) . ' 23:59:59', 'days' => max(1, min(90, (int) ($a['days'] ?? 7))),
|
||
'order_type' => (int) ($a['order_type'] ?? -1)],
|
||
],
|
||
'zyt_stats_prescription_orders' => [
|
||
'resource' => 'tcm.prescriptionOrder/lists', 'mode' => 'count', 'summary' => '处方业务订单',
|
||
'description' => '统计一段时间内处方业务订单的数量和金额（extend 中的 stats_* 字段），可按医生、医助筛选。',
|
||
'args' => ['start_date' => $date, 'end_date' => $date, 'doctor_id' => ['type' => 'integer', 'description' => '医生ID（可选）'],
|
||
'assistant_id' => ['type' => 'integer', 'description' => '医助ID（可选）']],
|
||
'required' => ['start_date', 'end_date'],
|
||
'note' => '金额口径以 extend 中 stats_* 字段为准（与后台处方订单列表顶部统计一致）。',
|
||
'map' => static fn (array $a) => array_filter(['start_time' => ($a['start_date'] ?? '') . ' 00:00:00', 'end_time' => ($a['end_date'] ?? '') . ' 23:59:59',
|
||
'doctor_id' => $a['doctor_id'] ?? null, 'assistant_id' => $a['assistant_id'] ?? null], static fn ($v) => $v !== null && $v !== ''),
|
||
],
|
||
'zyt_my_patients' => [
|
||
'resource' => 'firstvisit.myPatient/lists', 'summary' => '我的患者',
|
||
'description' => '按姓名/手机号关键字查找“我的患者”（医生看自己接诊过的，医助看自己负责的），返回诊单ID、最近就诊和下次预约。',
|
||
'args' => ['keyword' => ['type' => 'string', 'description' => '姓名或手机号（可选）'], 'page' => ['type' => 'integer', 'minimum' => 1]],
|
||
'required' => [],
|
||
'map' => static fn (array $a) => array_filter(['keyword' => $a['keyword'] ?? null], static fn ($v) => $v !== null && $v !== ''),
|
||
],
|
||
'zyt_roster' => [
|
||
'resource' => 'doctor.roster/lists', 'summary' => '医生排班',
|
||
'description' => '查询医生排班：日期、时段、出诊状态（1 出诊、2 停诊、3 休息、4 请假）、号源与已约数。',
|
||
'args' => ['start_date' => $date, 'end_date' => $date, 'doctor_id' => ['type' => 'integer', 'description' => '医生ID（可选）']],
|
||
'required' => ['start_date', 'end_date'],
|
||
'map' => static fn (array $a) => array_filter(['start_date' => $a['start_date'] ?? null, 'end_date' => $a['end_date'] ?? null,
|
||
'doctor_id' => $a['doctor_id'] ?? null], static fn ($v) => $v !== null && $v !== ''),
|
||
],
|
||
];
|
||
}
|
||
}
|